home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 May: Tool Chest / Developer CD Series Tool Chest (Apple Computer)(May 1999).iso / Tool Chest / Communications Toolbox / CTB Development Resources / CTB 411 Files / CommToolBoxHelp < prev   
Encoding:
Text File  |  1991-09-05  |  187.9 KB  |  6,083 lines  |  [TEXT/MPS ]
  1. æKY CopyrightNotice
  2. æC -----
  3. Copyright Apple Computer, Inc. 1985-1991, All rights reserved.
  4. 411 - CommToolBoxHelp - MPW 3.2 Final Release. 
  5.     Authors:        Gabriel Lopez
  6.                         Craig Hotchkiss
  7.                         James "im" Beninghaus
  8.  
  9. æKY Help
  10. CommToolBoxHelp
  11.  
  12. æKL AboutCommToolBoxHelp
  13. CommResources.h
  14. Connections.h
  15. CTBUtilities.h
  16. FileTransfers.h
  17. Terminals.h
  18.  
  19. æKY AboutCommToolBoxHelp
  20. æC
  21. __________________________________________________________________
  22. Version 1.0 Beta -- ETO #6?
  23.  
  24. Contains information from 
  25.     "Inside the Macintosh Communications Toolbox"
  26.     (Addison-Wesley, 1991)
  27. __________________________________________________________________
  28.  
  29.  
  30. æKY Connection Manager
  31. æC -----
  32. CMAbort                            CMIOKill
  33. CMAccept                        CMListen
  34. CMActivate                        CMMenu
  35. CMAddSearch                        CMNew
  36. CMBreak                            CMOpen
  37. CMChoose                        CMRead
  38. CMClearSearch                    CMRemoveSearch
  39. CMClose                            CMReset
  40. CMDefault                        CMResume
  41. CMDispose                        CMSetConfig
  42. CMEnglishToIntl                    CMSetRefCon
  43. CMEvent                            CMSetupCleanup
  44. CMGetConfig                        CMSetupFilter
  45. CMGetConnEnvirons                CMSetupItem
  46. CMGetCMVersion                    CMSetupPostFlight
  47. CMGetProcID                        CMSetupPreFlight
  48. CMGetRefCon                        CMSetupSetup
  49. CMGetToolName                    CMSetUserData
  50. CMGetUserData                    CMStatus
  51. CMGetVersion                    CMValidate
  52. CMIdle                            CMWrite
  53. CMIntlToEnglish                    InitCM
  54.  
  55. ConnRecord
  56.  
  57.  
  58. æKY Connections
  59. æC -----
  60. CMAbort                            CMIOKill
  61. CMAccept                        CMListen
  62. CMActivate                        CMMenu
  63. CMAddSearch                        CMNew
  64. CMBreak                            CMOpen
  65. CMChoose                        CMRead
  66. CMClearSearch                    CMRemoveSearch
  67. CMClose                            CMReset
  68. CMDefault                        CMResume
  69. CMDispose                        CMSetConfig
  70. CMEnglishToIntl                    CMSetRefCon
  71. CMEvent                            CMSetupCleanup
  72. CMGetConfig                        CMSetupFilter
  73. CMGetConnEnvirons                CMSetupItem
  74. CMGetCMVersion                    CMSetupPostFlight
  75. CMGetProcID                        CMSetupPreFlight
  76. CMGetRefCon                        CMSetupSetup
  77. CMGetToolName                    CMSetUserData
  78. CMGetUserData                    CMStatus
  79. CMGetVersion                    CMValidate
  80. CMIdle                            CMWrite
  81. CMIntlToEnglish                    InitCM
  82.  
  83. ConnRecord
  84.  
  85.  
  86. æKY ConnMgr
  87. æC -----
  88. CMAbort                            CMIOKill
  89. CMAccept                        CMListen
  90. CMActivate                        CMMenu
  91. CMAddSearch                        CMNew
  92. CMBreak                            CMOpen
  93. CMChoose                        CMRead
  94. CMClearSearch                    CMRemoveSearch
  95. CMClose                            CMReset
  96. CMDefault                        CMResume
  97. CMDispose                        CMSetConfig
  98. CMEnglishToIntl                    CMSetRefCon
  99. CMEvent                            CMSetupCleanup
  100. CMGetConfig                        CMSetupFilter
  101. CMGetConnEnvirons                CMSetupItem
  102. CMGetCMVersion                    CMSetupPostFlight
  103. CMGetProcID                        CMSetupPreFlight
  104. CMGetRefCon                        CMSetupSetup
  105. CMGetToolName                    CMSetUserData
  106. CMGetUserData                    CMStatus
  107. CMGetVersion                    CMValidate
  108. CMIdle                            CMWrite
  109. CMIntlToEnglish                    InitCM
  110.  
  111. ConnRecord
  112.  
  113. æKY ConnRecord
  114. æC -----
  115.     ConnHandle        =    ^ConnPtr;
  116.     ConnPtr            =    ^ConnRecord;
  117.     ConnRecord        =    RECORD
  118.         procID        :    INTEGER;
  119.         flags        :    CMRecFlags;
  120.         errCode        :    CMErr;
  121.         refCon        :    LONGINT;
  122.         userData    :    LONGINT;
  123.         defProc        :    ProcPtr;
  124.         config        :    Ptr;
  125.         oldConfig    :    Ptr;
  126.         asyncEOM    :    LONGINT;
  127.         reserved1    :    LONGINT;
  128.         reserved2    :    LONGINT;
  129.         cmPrivate    :    Ptr;
  130.         bufferArray    :    CMBuffers;
  131.         bufSizes    :    CMBufferSizes;
  132.         mluField    :    LONGINT;
  133.         asyncCount     :    CMBufferSizes;
  134.     END;
  135.  
  136. procID
  137. procID is the connection tool ID. This value is dynamically assigned 
  138. by the Connection Manager when your application calls CMGetProcID.
  139.  
  140. flags
  141. flags is a bit field that indicates certain specifics about a 
  142. connection when the connection record is first created. The bit masks 
  143. for    are as follows:    
  144.  
  145. TYPE
  146.         CMRecFlags    =        LONGINT;
  147. CONST
  148.         cmData    =            $00000001;
  149.         cmCntl    =            $00000002;
  150.         cmAttn    =            $00000004;
  151.  
  152.         cmDataClean    =        $00000100;
  153.         cmCntlClean    =        $00000200;
  154.         cmAttnClean    =        $00000400;
  155.  
  156.         cmNoMenus    =        $00010000;
  157.         cmQuiet    =            $00020000;
  158.  
  159. Your application can turn on the cmNoMenus or cmQuiet bits when it calls
  160. CMNew (discussed later in this chapter). The connection tool will set 
  161. the rest of these bits.
  162.     If the tool sets the cmData, cmCntl, or cmAttn bit, your application 
  163. can use a data, control, or attention channel. If the tool sets the    
  164. cmDataClean, cmCntlClean, or cmAttnClean bit, your application can use 
  165. a reliable (error-free, in order delivery) data, control, or attention 
  166. channel.
  167.     The connection tool will not display any custom menus if your 
  168. application sets the cmNoMenus bit. The connection tool will not display 
  169. any status dialog boxes or error alerts if your application sets the    
  170. cmQuiet bit. If your application turns the cmQuiet bit on, it is 
  171. responsible for displaying status dialog boxes and error alerts that 
  172. the tool would have displayed. Applications typically use these two 
  173. bits to hide the connection tool from the user.
  174.  
  175.  
  176. errCode
  177. errCode contains the last error encountered by the Connection Manager.
  178. Valid error codes are as follows:
  179.  
  180.  
  181. TYPE
  182.         CMErr                =        OSErr;
  183. CONST
  184.         cmGenericError        =        -1;
  185.         cmNoErr                =        0;
  186.         cmRejected             =         1;
  187.         cmFailed            =        2;
  188.         cmTimeOut            =        3;
  189.         cmNotOpen            =        4;
  190.         cmNotClosed            =        5;
  191.         cmNoRequestPending    =        6;
  192.         cmNotSupported        =        7;
  193.         cmNoTools            =        8;
  194.         cmUserCancel        =        9;
  195.  
  196.  
  197. refCon
  198. refCon is a four-byte field that your application can use.     
  199.  
  200.  
  201. userData
  202. userData is a four-byte field that your application can use.    
  203.  
  204.  
  205. defProc
  206. defProc is a procedure pointer to the main code resource of the 
  207. connection tool that will implement the connection protocol. The 
  208. connection tool’s main code resource is of type 'cdef'.
  209.  
  210.  
  211. config
  212. config is a pointer to a data block that is private to the connection
  213. tool. It can contain information such as data transfer rate or parity 
  214. for direct asynchronous connections, phone numbers for modem connections,
  215. or an address for an AppleTalk® network connection; the contents vary 
  216. from tool to tool.  
  217.     Your application can store the contents of config to save the state 
  218. of a connection in a document. The structure, size, and contents of the 
  219. configuration record are set by the tool. Your application can determine 
  220. the size of the configuration record by calling GetPtrSize, overwrite 
  221. its contents using BlockMove, and validate the contents with CMValidate.    
  222.     Your application can use CMGetConfig and CMSetConfig to manipulate 
  223. fields in this record. For details, see “Interfacing with a Scripting 
  224. Language,” later in this chapter. Your application can save the state 
  225. of the connection record by saving the string returned from CMGetConfig.
  226. Also, your application can restore the configuration of the    connection 
  227. record by passing a saved string to CMSetConfig.    
  228.     You can find more information about config from a connection tool 
  229. perspective in Chapter 8.
  230.  
  231.  
  232. oldConfig
  233. oldConfig is a pointer to a data block that is private to the 
  234. connection tool and contains the most recently saved version of config.
  235. Your application is responsible    for setting    oldConfig when the user 
  236. saves a session document.     
  237.  
  238.  
  239. reserved0, reserved1, and reserved2                  
  240. reserved0, reserved1, and reserved2 are fields that are reserved for 
  241. the Connection Manager. Your application must not use these fields.
  242.  
  243.  
  244. cmPrivate
  245. cmPrivate is a pointer to a data block that is private to the 
  246. connection tool. Your application must not use this field.
  247.  
  248.  
  249. bufferArray
  250. bufferArray is a set of pointers to buffers for the data, control, 
  251. and attention channels. These are the buffers that are used to read data
  252. to or write data from the entity. These buffers are allocated by the 
  253. connection tool and are the exclusive property of the connection tool; 
  254. your application should not use these buffers. The data type for 
  255. bufferArray is CMBuffers and is defined under the description of 
  256. bufSizes.               
  257.  
  258.  
  259. bufSizes
  260. bufSixes contains the actual sizes of the buffers and it, too, should
  261. not be manipulated directly by an application. The data type for bufSizes
  262. is CMBufferSizes, and is defined as follows:         
  263.  
  264. TYPE
  265.         CMBufFields = (
  266.                             cmDataIn,
  267.                             cmDataOut,
  268.                             cmCntlIn,
  269.                             cmCntlOut,
  270.                             cmAttnIn,
  271.                             cmAttnOut,
  272.                             cmRsrvIn,            {Reserved for Apple}
  273.                             cmRsrvOut);            {Reserved for Apple}
  274.  
  275.  
  276.         CMBuffers        =    ARRAY[CMBufFields] OF Ptr;
  277.         CMBufferSizes    =    ARRAY[CMBufFields] OF LONGINT;
  278.  
  279.  
  280. mluField
  281. mluField is a pointer to a private data structure that the Connection 
  282. Manager uses when searching the data stream.
  283.  
  284.  
  285. asyncCount
  286. asyncCount is used by completion routines to determine how many 
  287. bytes were actually transmitted or received on a particular channel. 
  288. Completion routines are discussed in more detail later in this chapter.
  289.  
  290.  
  291. æKY InitCM
  292. æFa Connections.a
  293. æFc Connections.h
  294. æFp Connections.p
  295. æMM
  296. æTN $A08B A0^.w=$101 (or #257)
  297. æDT InitCM:    CMErr;
  298. æC -----
  299. Initializing the Connection Manager 
  300.  
  301. Function        InitCM  :  CMErr;
  302.  
  303. Description:    InitCM initializes the Connection Manager. Your 
  304.                 application should call this routine only once, after 
  305.                 calling the standard Macintosh Toolbox initialization 
  306.                 routines.
  307.  
  308.                 Warning    :    Your application must initialize the 
  309.                 Communications Resource Manager    (by calling InitCRM) and
  310.                 then the Communications Toolbox    Utilities (by calling 
  311.                 InitCTBUtilities), whether or not it uses any of their 
  312.                 calls, before it initializes the Connection Manager.
  313.                 
  314.                 InitCM returns an operating system error code if 
  315.                 appropriate. Your application must check for the 
  316.                 presence of the Communications Toolbox before calling 
  317.                 this function. Sample code under “Determining Whether 
  318.                 the Managers are Installed” in Appendix C shows you
  319.                 how your application can make this check.
  320.  
  321. Result Codes:    cmGenericError, cmNoErr, cmNoTools.
  322.  
  323.  
  324. æKY CMGetProcID
  325. æFa Connections.a 
  326. æFc Connections.h 
  327. æFp Connections.p 
  328. æMM 
  329. æTN $A08B A0^.w=$107 (or #263)
  330. æDT CMGetProcID(name: Str255): INTEGER;
  331. æC -----
  332. Getting current procID information
  333.  
  334. Function        CMGetProcID(name: Str255): INTEGER;
  335.  
  336. Description:    Your application should call CMGetProcID just before 
  337.                 creating a new connection record, to find out the 
  338.                 CMGetProcID of a tool.
  339.                 
  340.                 name specifies a connection tool. If a connection tool 
  341.                 is available with the specified name, its procID is 
  342.                 returned. If name references a nonexistent connection 
  343.                 tool, CMGetProcID returns –1. 
  344.  
  345.  
  346. æKY CMNew
  347. æFa Connections.a 
  348. æFc Connections.h 
  349. æFp Connections.p 
  350. æMM 
  351. æTN $A08B A0^.w=$108 (or #264)
  352. æDT CMNew(procID: INTEGER; flags: CMRecFlags; desiredSizes: CMBufferSizes; refCon: LONGINT; userData: LONGINT): ConnHandle;
  353. æC -----
  354. Creating a connection record
  355.  
  356. Function        CMNew(procID : INTEGER; flags : CMRecFlags; 
  357.                 desiredSizes : CMBufferSizes; refCon : LONGINT; 
  358.                 userData : LONGINT) : ConnHandle;
  359.  
  360. Description:    Before your application can open a connection, it must 
  361.                 create a connection record so the Connection Manager 
  362.                 knows what type of connection to establish. CMNew 
  363.                 creates a new connection record; fills in the fields 
  364.                 that it can, based upon the parameters that were passed
  365.                 to it; and returns a handle to the new record in 
  366.                 ConnHandle. CMNew automatically makes two calls to 
  367.                 CMDefault (which is described later in this chapter) to
  368.                 fill in config and oldConfig. The Connection Manager 
  369.                 then loads the connection tool main code resource, 
  370.                 moves it high in the current heap, and locks it. If an
  371.                 error occurs that prevents a new connection record from
  372.                 being created (for example, running out of memory), 
  373.                 CMNew passes back NIL in ConnHandle.
  374.                 
  375.                 procID is dynamically assigned by the Connection Manager
  376.                 to tools at run time. Applications should not store 
  377.                 procID    values in settings files. Instead, they should 
  378.                 store tool names, which can be converted to procID 
  379.                 values with the    CMGetProcID routine. Your application 
  380.                 should use the ID that CMGetProcID returns for procID.    
  381.  
  382.                 flags is a bit field with the following masks:     
  383.  
  384.                 CONST
  385.                     cmData            =        $00000001;
  386.                     cmCntl            =        $00000002;
  387.                     cmAttn            =        $00000004;
  388.  
  389.                     cmDataClean        =        $00000100;
  390.                     cmCntlClean        =        $00000200;
  391.                     cmAttnClean        =        $00000400;
  392.         
  393.                     cmNoMenus        =        $00010000;
  394.                     cmQuiet            =        $00020000;
  395.     
  396.                     flags represents a request from your application for
  397.                 a level of connection service. If your application sets 
  398.                 cmNoMenus, the connection tool will not display any 
  399.                 custom menus. If your application sets cmQuiet, the 
  400.                 connection tool will not display any windows. 
  401.                 Applications typically use these bits to hide the 
  402.                 connection tool from the user.
  403.                     The connection tool sets the other bits, and returns
  404.                 in the flags field of the connection record the level of
  405.                 connection service that it grants your application. The
  406.                 flags field is discussed in “Connection Record Data    
  407.                 Structure,” earlier in this chapter.
  408.                     Apple Computer, Inc. has reserved the bits of flags
  409.                 not shown in this manual. Do not use them, or your code
  410.                 may not work in the future.
  411.  
  412.                 desiredSizes specifies buffer sizes that your 
  413.                 application requests for its read, write, control read,
  414.                 control write, attention read, and attention write 
  415.                 channels. Your application can specify the sizes that 
  416.                 it wants when it calls CMNew, but the connection tool 
  417.                 might not provide the requested sizes. To have the tool 
  418.                 set the size of these buffers, your application should 
  419.                 put zeros in the array. These buffers become the 
  420.                 exclusive property of the connection tool and should not
  421.                 be manipulated by the application in any way. The actual
  422.                 buffer sizes are kept in the bufSizes field of the 
  423.                 connection record.     
  424.  
  425.                 refCon and userData are fields that your application can
  426.                 use.        
  427.  
  428.  
  429. æKY CMDefault
  430. æFa Connections.a 
  431. æFc Connections.h 
  432. æFp Connections.p 
  433. æMM 
  434. æTN $A08B A0^.w=$118 (or #280)
  435. æDT CMDefault(VAR theConfig: Ptr; procID: INTEGER; allocate: BOOLEAN);
  436. æC -----
  437. Initializing the configuration record
  438.  
  439. Procedure        CMDefault(VAR theConfig: Ptr; procID: INTEGER; allocate: 
  440.                 BOOLEAN);
  441.  
  442. Description:     CMDefault fills the specified configuration record with
  443.                 the default configuration specified by the connection 
  444.                 tool. CMNew calls this procedure automatically when it 
  445.                 fills in the config    and oldConfig fields in a new 
  446.                 connection record.
  447.                 
  448.                 If allocate is TRUE, the tool allocates space for 
  449.                 theConfig in the current heap zone.
  450.  
  451.  
  452. æKY CMValidate
  453. æFa Connections.a 
  454. æFc Connections.h 
  455. æFp Connections.p 
  456. æMM 
  457. æTN $A08B A0^.w=$117 (or #279)
  458. æDT CMValidate(hConn: ConnHandle): BOOLEAN;
  459. æC -----
  460. Validating the configuration record
  461.  
  462. Function        CMValidate(hConn: ConnHandle): BOOLEAN;
  463.  
  464. Description:    CMValidate performs an internal consistency check on the
  465.                 configuration and private data records of the connection
  466.                 record. CMNew and CMSetConfig call this routine after 
  467.                 they have created a new connection record, to make sure
  468.                 that the record contains values identical to those 
  469.                 specified by the connection tool.
  470.                 
  471.                 If the validation fails, the Connection Manager returns    
  472.                 TRUE and the tool fills the configuration record with 
  473.                 default values by calling CMDefault.    
  474.                     Your application can call this routine after 
  475.                 restoring a configuration, to verify that the connection
  476.                 record contains the correct information, in a manner 
  477.                 similar to that shown next.
  478.  
  479.                 BlockMove(saveConfig,hConn^^.config,
  480.                     GetPtrSize(hConn^^.config));
  481.                 IF CMValidate(hConn) THEN BEGIN
  482.                     { validate failed }
  483.                     END
  484.                     ELSE BEGIN
  485.                             { validate succeeded }
  486.                             END
  487.  
  488.  
  489. æKY CMChoose
  490. æFa Connections.a 
  491. æFc Connections.h 
  492. æFp Connections.p 
  493. æMM 
  494. æTN $A08B A0^.w=$124 (or #292)
  495. æDT CMChoose(VAR hConn: ConnHandle; where: Point; idleProc: ProcPtr): INTEGER;
  496. æC -----
  497. Configuring a connection tool
  498.  
  499. Function        CMChoose(VAR hConn:ConnHandle; where: Point; idleProc: 
  500.                 ProcPtr):INTEGER;
  501.  
  502. Description:     An application can configure a connection tool in one of
  503.                 three ways. The easiest and most straightforward way is
  504.                 by calling the CMChoose routine. This routine presents 
  505.                 the user with a dialog box.
  506.                     The second way an application can configure a 
  507.                 connection tool is by presenting the user with a custom 
  508.                 tool-settings dialog box. This method is much more 
  509.                 difficult, and involves calling six routines. The 
  510.                 routines are described in the next section, 
  511.                 “Custom Configuration of a Connection Tool,” and “The
  512.                 Custom Tool-Settings Dialog Box” in Appendix C provides
  513.                 example code.
  514.                     The third way your application can configure a 
  515.                 connection tool is by using the scripting language 
  516.                 interface, described in “Interfacing With a Scripting 
  517.                 Language,” later in this chapter. This method allows 
  518.                 your application to bypass user interface elements.
  519.                 
  520.                 where is the point, specified in global coordinates,
  521.                 where the upper-left corner of the dialog box should 
  522.                 appear. It is recommended that your application place 
  523.                 the dialog box as close as possible to the upper-left 
  524.                 corner of the screen, because the size of the dialog box
  525.                 varies from tool to tool.
  526.  
  527.                 idleProc is a procedure with no parameters that the 
  528.                 Connection Manager will automatically call every time 
  529.                 CMChoose calls the setup dialog box filter procedure.     
  530.                 Pass NIL if your application has no idleProc.         
  531.  
  532.                 CMChoose returns one of the following values:    
  533.  
  534.                 CONST
  535.                     chooseDisaster        =        -2;
  536.                     choose    Failed        =        -1;
  537.                     chooseAborted        =        0;
  538.                     chooseOKMinor        =        1;
  539.                     chooseOKMajor        =        2;
  540.                     chooseCancel        =        3;
  541.  
  542.                     chooseDisaster means that the CMChoose operation 
  543.                 failed, destroyed the connection record, and returned 
  544.                 NIL    in the connection handle.
  545.                 
  546.                     chooseFailed means that the CMChoose operation 
  547.                 failed and the connection record was not changed.
  548.  
  549.                     chooseAborted means that the user started to change
  550.                 the connection while it was still open but did not 
  551.                 commit the changes. When users try to change connection 
  552.                 tools while the connection is still open, the Connection
  553.                 Manager prompts them with a dialog box that asks if they
  554.                 want to make the change. If the user clicks No in this 
  555.                 dialog box, the CMChoose routine returns chooseAborted.    
  556.  
  557.                     chooseOKMinor means that the user clicked OK in the
  558.                 dialog box but did not change the connection tool being
  559.                 used.
  560.  
  561.                     chooseOKMajor means that the user selected OK in the
  562.                 dialog box and also changed the connection tool being 
  563.                 used. The Connection Manager then destroys the old 
  564.                 connection handle by calling CMDispose. The connection 
  565.                 is closed down, all pending read and write operations 
  566.                 are terminated, and a new connection handle is returned
  567.                 in hConn.    
  568.  
  569.                 chooseCancel means that the user clicked Cancel in the
  570.                 dialog box.    
  571.  
  572.  
  573. æKY CMSetupPreflight
  574. æFa Connections.a 
  575. æFc Connections.h 
  576. æFp Connections.p 
  577. æMM 
  578. æTN $A08B A0^.w=$123 (or #291)
  579. æDT CMSetupPreflight(procID: INTEGER; VAR magicCookie: LONGINT): Handle;
  580. æC -----
  581. Setting up the custom tool-settings dialog box
  582.  
  583. Function        CMSetupPreflight(procID: INTEGER; VAR magicCookie: 
  584.                 LONGINT): Handle;
  585.  
  586. Description:     CMSetupPreflight returns a handle to a dialog item list 
  587.                 that your application appends to the custom 
  588.                 tool-settings dialog box. The handle comes from the 
  589.                 connection tool. (The calling application uses 
  590.                 AppendDITL, discussed in Chapter 7.) This handle is not 
  591.                 a resource handle. Your application is responsible for 
  592.                 disposing of the handle when done with it.
  593.                     The connection tool can use CMSetupPreflight to 
  594.                 allocate a block of private storage, and to store the 
  595.                 pointer to that block in magicCookie. The magicCookie 
  596.                 value should be passed to the other routines that are 
  597.                 used to set    up the custom tool-settings dialog box.
  598.                 
  599.                 procID is the ID for the connection tool that is being 
  600.                 configured. Your application should get this value by 
  601.                 using the CMGetProcID routine, discussed earlier in 
  602.                 this chapter.
  603.  
  604.                 Note:      The refcon of the custom tool-settings dialog 
  605.                 box should point to a data structure (shown next) in 
  606.                 which the first two bytes are the tool procID and the 
  607.                 next four bytes are magicCookie. UserItem routines,for 
  608.                 example, may require procID    to obtain tool resources.     
  609.  
  610.                 TYPE
  611.                     chooseDLOGdata        =    RECORD
  612.                         procID            :    INTEGER
  613.                         magicCookie        :    LONGINT
  614.                 END;
  615.  
  616.  
  617. æKY CMSetupSetup
  618. æFa Connections.a 
  619. æFc Connections.h 
  620. æFp Connections.p 
  621. æMM 
  622. æTN $A08B A0^.w=$119 (or #281)
  623. æDT CMSetupSetup(procID: INTEGER; theConfig: Ptr; count: INTEGER; theDialog: DialogPtr; VAR magicCookie: LONGINT);
  624. æC -----
  625. Setting up custom tool-settings dialog box items
  626.  
  627. Procedure        CMSetupSetup(procID: INTEGER; theConfig: Ptr; count: 
  628.                 INTEGER; theDialog: DialogPtr; VAR magicCookie: 
  629.                 LONGINT);
  630.  
  631. Description:    CMSetupSetup tells the connection tool to set up 
  632.                 controls (such as radio buttons or check boxes) in the 
  633.                 dialog item list returned by CMSetupPreflight.
  634.                 
  635.                 procID is the ID for the connection tool that is being 
  636.                 configured. Your application should use the same value 
  637.                 for procIDas it passed to CMSetupPreflight.    
  638.  
  639.                 theConfig is a pointer to a configuration record for the
  640.                 tool being configured.    
  641.  
  642.                 count is the number of the first item in the dialog item
  643.                 list appended to the dialog box.
  644.  
  645.                 theDialog is the dialog box in which configuration is 
  646.                 taking place.    
  647.  
  648.                 magicCookie is a pointer to private storage for the 
  649.                 connection tool.    
  650.  
  651.  
  652. æKY CMSetupFilter
  653. æFa Connections.a 
  654. æFc Connections.h 
  655. æFp Connections.p 
  656. æMM 
  657. æTN $A08B A0^.w=$122 (or #290)
  658. æDT CMSetupFilter(procID: INTEGER; theConfig: Ptr; count: INTEGER; theDialog: DialogPtr; VAR theEvent: EventRecord; VAR theItem: INTEGER; VAR magicCookie: LONGINT): BOOLEAN;
  659. æC -----
  660. Filtering custom tool settings dialog box events
  661.  
  662. Function        CMSetupFilter(procID: INTEGER; theConfig: Ptr; count:
  663.                 INTEGER; theDialog: DialogPtr; VAR theEvent: 
  664.                 EventRecord; VAR theItem: INTEGER; VAR magicCookie: 
  665.                 LONGINT): BOOLEAN;
  666.  
  667. Description:    Your application calls CMSetupFilter as a filter 
  668.                 procedure before it calls the standard modal dialog box
  669.                 filter procedure for the custom tool-settings dialog box.
  670.                 This routine allows connection tools to filter events in
  671.                 the custom tool-settings dialog box.
  672.                 
  673.                 procID is the ID for the connection tool that is being 
  674.                 configured. Your application should use the same value 
  675.                 for procID as it passed to CMSetupPreflight.    
  676.  
  677.                 theConfig is a pointer to the configuration record for
  678.                 the tool being    configured.
  679.  
  680.                 count is the number of the first item in the dialog item
  681.                 list appended to the dialog box.
  682.  
  683.                 theDialog is the dialog box performing the configuration.    
  684.  
  685.                 theEvent is the event record for which filtering is to
  686.                 take place.    
  687.  
  688.                 theItem can return the item clicked in the dialog box.    
  689.  
  690.                 magicCookie is a pointer to private storage for the 
  691.                 connection tool.    
  692.  
  693.                 If the event passed in was handled, CMSetupFilter 
  694.                 returns TRUE. FALSE    indicates that your application 
  695.                 should perform standard dialog box filtering.
  696.  
  697.  
  698. æKY CMSetupItem
  699. æFa Connections.a 
  700. æFc Connections.h 
  701. æFp Connections.p 
  702. æMM 
  703. æTN $A08B A0^.w=$11A (or #282)
  704. æDT CMSetupItem(procID: INTEGER; theConfig: Ptr; count: INTEGER; theDialog: DialogPtr; VAR theItem: INTEGER; VAR magicCookie: LONGINT);
  705. æC -----
  706. Processing custom tool-settings dialog box events
  707.  
  708. Procedure        CMSetupItem(procID: INTEGER; theConfig: Ptr; count: 
  709.                 INTEGER; theDialog: DialogPtr; VAR theItem: INTEGER; 
  710.                 VAR magicCookie: LONGINT);
  711.  
  712. Description:    CMSetupItem processes events for controls in the custom
  713.                 tool-settings dialog box.
  714.                 
  715.                 procID is the ID for the connection tool being 
  716.                 configured. Your application should use the same value 
  717.                 for procID as it passed to CMSetupPreflight.        
  718.  
  719.                 theConfig is a pointer to the configuration record for 
  720.                 the tool being    configured.
  721.  
  722.                 count is the number of the first item in the dialog item
  723.                 list appended to the dialog box.
  724.  
  725.                 theDialog is the dialog box performing the configuration.    
  726.  
  727.                 theItem is the item clicked in the dialog box. This 
  728.                 value can be modified and sent back.
  729.  
  730.                 magicCookie is a pointer to private storage for the 
  731.                 connection tool.    
  732.  
  733.  
  734. æKY CMSetupCleanup
  735. æFa Connections.a 
  736. æFc Connections.h 
  737. æFp Connections.p 
  738. æMM 
  739. æTN $A08B A0^.w=$11B (or #283)
  740. æDT CMSetupCleanup(procID: INTEGER; theConfig: Ptr; count: INTEGER; theDialog: DialogPtr; VAR magicCookie: LONGINT);
  741. æC -----
  742. Performing clean-up operations
  743.  
  744. Procedure        CMSetupCleanup(procID: INTEGER; theConfig: Ptr; count: 
  745.                 INTEGER; theDialog: DialogPtr; VAR magicCookie: LONGINT);
  746.  
  747. Description:    CMSetupCleanup disposes of any storage allocated in 
  748.                 CMSetupPreflight and performs other clean-up operations.
  749.                 If your application needs to shorten a dialog box, it 
  750.                 should do so after calling this routine.
  751.                 
  752.                 procID is the ID for the connection tool that is being 
  753.                 configured. Your application should use the same value 
  754.                 for procID as it passed to CMSetupPreflight.    
  755.  
  756.                 theConfig is a pointer to the configuration record for 
  757.                 the tool being    configured.
  758.  
  759.                 count is the number of the first item in the dialog item
  760.                 list appended to the dialog box.
  761.  
  762.                 theDialog is the dialog box performing the configuration.    
  763.  
  764.                 magicCookie is a pointer to private storage for the 
  765.                 connection tool.    
  766.  
  767.  
  768. æKY CMSetupPostflight
  769. æFa Connections.a 
  770. æFc Connections.h 
  771. æFp Connections.p 
  772. æMM 
  773. æTN $A08B A0^.w=$12B (or #299)
  774. æDT CMSetupPostflight(procID: INTEGER);
  775. æC -----
  776. Closing the tool file
  777.     
  778. Procedure        CMSetupPostflight(procID:INTEGER);
  779.  
  780. Description:    CMSetupPostflight closes the tool file if it is not 
  781.                 being used by any sessions.
  782.                 
  783.                 procID is the ID for the connection tool that is being 
  784.                 configured. Your application should use the same value 
  785.                 for procID as it passed to CMSetupPreflight.    
  786.  
  787.  
  788. æKY CMGetConfig
  789. æFa Connections.a 
  790. æFc Connections.h 
  791. æFp Connections.p 
  792. æMM 
  793. æTN $A08B A0^.w=$11C (or #284)
  794. æDT CMGetConfig(hConn: ConnHandle): Ptr;
  795. æC -----
  796. Getting the configuration string    
  797.  
  798. Function        CMGetConfig(hConn: ConnHandle): Ptr;
  799.  
  800. Description:    CMGetConfig gets a configuration string from the 
  801.                 connection tool.
  802.                 
  803.                 CMGetConfig returns a null-terminated, C-style string 
  804.                 from the connection tool containing tokens that fully 
  805.                 describe the configuration of the connection record. For
  806.                 an example, see the description of the next routine. If
  807.                 an error occurs, CMGetConfig returns NIL.        
  808.                     It is the responsibility of your application to 
  809.                 dispose of Ptr.    
  810.  
  811.  
  812. æKY CMSetConfig
  813. æFa Connections.a 
  814. æFc Connections.h 
  815. æFp Connections.p 
  816. æMM 
  817. æTN $A08B A0^.w=$11D (or #285)
  818. æDT CMSetConfig(hConn: ConnHandle; thePtr: Ptr): INTEGER;
  819. æC -----
  820. Setting the configuration with a string    
  821.  
  822. Function        CMSetConfig(hConn: ConnHandle; thePtr: Ptr): INTEGER;
  823.  
  824. Description:    CMSetConfig passes a configuration string to the 
  825.                 connection tool.
  826.                 
  827.                 CMSetConfig passes a null-terminated, C-style string 
  828.                 (see the example string    later in this section) to the
  829.                 connection tool for parsing. The string is pointed to by
  830.                 thePtr and must contain tokens that describe the 
  831.                 configuration of the connection record. The string can 
  832.                 be any length.
  833.                     CMSetConfig ignores items it does not recognize or 
  834.                 find relevant; such an occurrence causes the connection
  835.                 tool to stop parsing the string and to return the 
  836.                 character position where the error occurred. If the 
  837.                 connection tool successfully parses the string, it 
  838.                 returns cmNoErr. If the    connection tool does not 
  839.                 successfully parse the string, it returns one of the 
  840.                 following values: a number less than –1 to indicate an 
  841.                 OSErr,–1 to indicate an unknown error, or a positive 
  842.                 number to indicate the character position where parsing
  843.                 was stopped.
  844.                     Individual connection tools are responsible for the
  845.                 parsing operation.
  846.  
  847. Sample:            A null-terminated, C-style configuration string    
  848.     
  849.                 Baud 9600 dataBits 8 Parity None StopBits 1 Port 
  850.                 "Modem Port" Handshake None HoldConnection False 
  851.                 RemindDisconnect False\0
  852.  
  853.  
  854. æKY CMOpen
  855. æFa Connections.a 
  856. æFc Connections.h 
  857. æFp Connections.p 
  858. æMM 
  859. æTN $A08B A0^.w=$10B (or #267)
  860. æDT CMOpen(hConn: ConnHandle; async: BOOLEAN; completor: ProcPtr; timeout: LONGINT): CMErr;
  861. æC -----
  862. Opening a connection
  863.  
  864. Function        CMOpen(hConn: ConnHandle; async: BOOLEAN; completor: 
  865.                 ProcPtr; timeout: LONGINT): CMErr;
  866.  
  867. Description:    CMOpen attempts to open a connection, based on 
  868.                 information contained in a connection record.
  869.                 
  870.                 hConn points to the connection record for the new 
  871.                 connection.    
  872.  
  873.                 async specifies whether the opening request is 
  874.                 asynchronous. If your application makes an asynchronous
  875.                 request, CMOpen returns cmNoErr    immediately.
  876.  
  877.                 completor specifies the completion routine to be called
  878.                 upon completion of an asynchronous open request. 
  879.                 Completion routines are discussed in greater detail 
  880.                 later in this chapter, in the section “Completion 
  881.                 Routines.”
  882.  
  883.                 CMOpen specifies a time period, in ticks, within which 
  884.                 must be    timeout completed before the connection tool 
  885.                 returns a cmTimeOut error. For no timeout, use –1. For a
  886.                 single attempt to open the connection, use 0. Some 
  887.                 connection tools ignore this parameter.
  888.  
  889.                 If no error occurs during the open attempt, CMOpen
  890.                 returns cmNoErr. CMOpen returns a negative number if an
  891.                 operating system error occurred, or a positive number if
  892.                 a Connection Manager error occurred.
  893.  
  894. Result Codes    cmGenericError, cmNoErr, cmRejected, cmFailed, cmTimeout,
  895.                 cmNotClosed, cmNotSupported, cmUserCancel.
  896.  
  897.  
  898. æKY CMClose
  899. æFa Connections.a 
  900. æFc Connections.h 
  901. æFp Connections.p 
  902. æMM 
  903. æTN $A08B A0^.w=$10E (or #270)
  904. æDT CMClose(hConn: ConnHandle; async: BOOLEAN; completor: ProcPtr; timeout: LONGINT; now: BOOLEAN): CMErr;
  905. æC -----
  906. Closing a connection    
  907.  
  908. Function        CMClose(hConn: ConnHandle; async: BOOLEAN; completor: 
  909.                 ProcPtr; timeout: LONGINT; now: BOOLEAN): CMErr;
  910.  
  911. Description:    CMClose closes a connection that is already open or in 
  912.                 the process of opening.
  913.                 
  914.                 async specifies whether or not the close request is 
  915.                 asynchronous. If your application requests an 
  916.                 asynchronous close, CMClose returns noErr immediately.
  917.  
  918.                 completor specifies the completion routine to be called 
  919.                 upon completion of an asynchronous close request.
  920.                 Completion routines are discussed in greater detail 
  921.                 later in this chapter, in the section “Completion 
  922.                 Routines.”
  923.  
  924.                 timeout specifies a time period, in ticks, within which 
  925.                 the close operation must be completed before the 
  926.                 connection tool returns a cmTimeOut error. For no 
  927.                 timeout, use –1. For a single attempt to close the 
  928.                 connection, use 0. Some connection tools ignore this 
  929.                 parameter.
  930.  
  931.                 When now is TRUE, the connection tool closes the 
  932.                 connection immediately.    When now is FALSE, the 
  933.                 connection tool waits until all pending input and output
  934.                 have finished before closing the connection.
  935.  
  936. Result Codes    cmGenericError, cmNoErr, cmRejected, cmFailed, cmTimeout, 
  937.                 cmNotOpen, cmNotSupported, cmUserCancel.
  938.                 
  939.                 
  940. æKY CMAbort
  941. æFa Connections.a 
  942. æFc Connections.h 
  943. æFp Connections.p 
  944. æMM 
  945. æTN $A08B A0^.w=$10F (or #271)
  946. æDT CMAbort(hConn: ConnHandle): CMErr;
  947. æC -----
  948. Aborting a connection    
  949.  
  950. Function        CMAbort(hConn: ConnHandle): CMErr;
  951.  
  952. Description:    CMAbort tells the Connection Manager to stop trying to 
  953.                 complete a pending asynchronous open request. Any open 
  954.                 completion routines are executed. Your application can 
  955.                 also call this routine to stop an outstanding CMListen.
  956.                 
  957.                 hConn specifies the connection this routine affects.    
  958.  
  959. Result Codes    cmGenericError, cmNoErr, cmRejected, cmFailed, cmNotOpen,
  960.                 cmNoRequestPending, cmNotSupported.
  961.  
  962.  
  963. æKY CMDispose
  964. æFa Connections.a 
  965. æFc Connections.h 
  966. æFp Connections.p 
  967. æMM 
  968. æTN $A08B A0^.w=$109 (or #265)
  969. æDT CMDispose(hConn: ConnHandle);
  970. æC -----
  971. Disposing of a connection record
  972.  
  973. Procedure        CMDispose(hConn: ConnHandle);
  974.  
  975. Description:    CMDispose disposes of the connection record and all 
  976.                 associated data structures.    It is up to the connection
  977.                 tool to decide whether or not to wait for all pending 
  978.                 read and write operations to complete before closing and
  979.                 disposing of the connection.
  980.                 
  981.                 hConn specifies the connection record disposed of by 
  982.                 this routine.    
  983.  
  984.  
  985. æKY CMIdle
  986. æFa Connections.a 
  987. æFc Connections.h 
  988. æFp Connections.p 
  989. æMM 
  990. æTN $A08B A0^.w=$10A (or #266)
  991. æDT CMIdle(hConn: ConnHandle);
  992. æC -----
  993. Idle procedure
  994.  
  995. Procedure        CMIdle(hConn: ConnHandle);
  996.  
  997. Description:    Your application should call CMIdle at least once every
  998.                 time it goes through its main event loop, so that the 
  999.                 connection tool can perform idle-loop tasks.
  1000.                 
  1001.                 hConn specifies the connection for which idle-loop tasks
  1002.                 are to be performed.    
  1003.  
  1004.  
  1005. æKY CMListen
  1006. æFa Connections.a 
  1007. æFc Connections.h 
  1008. æFp Connections.p 
  1009. æMM 
  1010. æTN $A08B A0^.w=$10C (or #268)
  1011. æDT CMListen(hConn: ConnHandle; async: BOOLEAN; completor: ProcPtr; timeout: LONGINT): CMErr;
  1012. æC -----
  1013. Listening for incomming connection requests
  1014.     
  1015. Function        CMListen(hConn: ConnHandle; async: BOOLEAN; completor: 
  1016.                 ProcPtr; timeout: LONGINT): CMErr;
  1017.  
  1018. Description:    CMListen “listens” for a connection request from another
  1019.                 entity. Your application, after it calls CMListen, 
  1020.                 should call CMStatus (which is described later in this 
  1021.                 section) to see if a connection request has been 
  1022.                 received (by checking the cmStatusIncomingCallPresent
  1023.                 bit).
  1024.                 
  1025.                 async specifies whether or not the opening request is 
  1026.                 asynchronous. If your application makes an asynchronous 
  1027.                 request, CMListen returns cmNoErr immediately. If your 
  1028.                 application makes a synchronous request, CMListen stays
  1029.                 in a “listen loop” until it receives the connection 
  1030.                 request.
  1031.  
  1032.                 completor specifies the completion routine that the
  1033.                 Connection Manager calls after it is done listening for
  1034.                 the connection request. Completion routines are called 
  1035.                 only after asynchronous calls to CMListen. “Completion
  1036.                 Routines,” later in this chapter, discusses completion
  1037.                 routines in more detail.
  1038.  
  1039.                 timeout specifies a time period, in ticks, within which 
  1040.                 a connection request must be received before the 
  1041.                 connection tool returns a cmTimeOut error. For no 
  1042.                 timeout, use –1. For a single listen, use 0. Some 
  1043.                 connection tools ignore this parameter.
  1044.  
  1045. Result Codes    cmGenericError, cmNoErr, cmRejected, cmFailed, cmTimeout,
  1046.                 cmNotClosed, cmNotSupported, cmUserCancel.
  1047.  
  1048.  
  1049. æKY CMStatus
  1050. æFa Connections.a 
  1051. æFc Connections.h 
  1052. æFp Connections.p 
  1053. æTN $A08B A0^.w=$110 (or #272)
  1054. æDT CMStatus(hConn: ConnHandle; VAR sizes: CMBufferSizes; VAR flags: CMStatFlags): CMErr;
  1055. æC -----
  1056. Getting connection status information
  1057.  
  1058. Function        CMStatus(hConn: ConnHandle; VAR sizes: CMBufferSizes; 
  1059.                 VAR flags: CMStatFlags): CMErr;
  1060.  
  1061. Description:    CMStatus returns a variety of useful status information 
  1062.                 about a connection.    Your application can call this 
  1063.                 routine at interrupt level.
  1064.                 
  1065.                 sizes is a variable of type CMBufferSizes that contains
  1066.                 the number of characters to be read or written on the 
  1067.                 data, control, and attention channels. The indexes of 
  1068.                 the array are as follows:
  1069.  
  1070.                 cmDataIn, cmDataOut, cmCntlIn, cmCntlOut, cmAttnIn, 
  1071.                 cmAttnOut, cmRsrvIn, cmRsrvOut.
  1072.  
  1073.                 flags is a bit field with the following masks:    
  1074.  
  1075.                 CONST
  1076.                                         {tool is opening connection}
  1077.                     cmStatusOpening                =    $00000001;
  1078.                                         {connection is open}
  1079.                     cmStatusOpen                =    $00000002;
  1080.                                         {tool is closing connection}
  1081.                     cmStatusClosing                =    $00000004;
  1082.                                         {data present on data channel}
  1083.                     cmStatusDataAvail            =    $00000008;
  1084.                                         {data present on cntl channel}
  1085.                     cmStatusCntlAvail            =    $00000010;
  1086.                                         {data present on attn channel}
  1087.                     cmStatusAttnAvail            =    $00000020;
  1088.                                         {data read pending}
  1089.                     cmStatusDRPend                =    $00000040;
  1090.                                         {data write pending}
  1091.                     cmStatusDWPend                =    $00000080;
  1092.                                         {cntl read pending}
  1093.                     cmStatusCRPend                =    $00000100;
  1094.                                         {cntl write pending}
  1095.                     cmStatusCWPend                =    $00000200;
  1096.                                         {attn read pending}
  1097.                     cmStatusARPend                =    $00000400;
  1098.                                         {attn write pending}
  1099.                     cmStatusAWPend                =    $00000800;
  1100.                                         {tool is breaking the connection}
  1101.                     cmStatusBreakPending        =    $00001000;
  1102.                                         {tool is “listening” for data}
  1103.                     cmStatusListenPend            =    $00002000;
  1104.                                         {call waiting for tool to handle}
  1105.                     cmStatusIncomingCallPresent    =    $00004000;
  1106.  
  1107.  
  1108.                 TYPE
  1109.                     CMStatFlags                    =    LONGINT;
  1110.  
  1111.  
  1112. Result Codes    cmGenericError, cmNoErr, cmNotSupported.
  1113.  
  1114.  
  1115. æKY CMAccept
  1116. æFa Connections.a 
  1117. æFc Connections.h 
  1118. æFp Connections.p 
  1119. æMM 
  1120. æTN $A08B A0^.w=$10D (or #269)
  1121. æDT CMAccept(hConn: ConnHandle; accept: BOOLEAN): CMErr;
  1122. æC -----
  1123. Accepting or rejecting a connection request
  1124.  
  1125. Function        CMAccept(hConn:ConnHandle; accept:BOOLEAN): CMErr;
  1126.  
  1127. Description:    CMAccept accepts or rejects an incoming connection 
  1128.                 request.    
  1129.                 
  1130.                 Typically, an application will perform some actions 
  1131.                 after a CMListen, the results of which determine whether
  1132.                 to accept the request. CMAccept cannot be called from 
  1133.                 interrupt level.
  1134.  
  1135. Result Codes    cmGenericError, cmNoErr, cmRejected, cmFailed, 
  1136.                 cmNoRequestPending, cmNotSupported.
  1137.  
  1138.  
  1139. æKY CMIOKill
  1140. æFa Connections.a 
  1141. æFc Connections.h 
  1142. æFp Connections.p 
  1143. æMM 
  1144. æTN $A08B A0^.w=$129 (or #297)
  1145. æDT CMIOKill(hConn: ConnHandle; which: INTEGER): CMErr;
  1146. æC -----
  1147. Stopping an asynchronous input/output request
  1148.  
  1149. Function        CMIOKill(hConn: ConnHandle; which: INTEGER): CMErr;
  1150.  
  1151. Description:    CMIOKill terminates any pending input/output (I/O) 
  1152.                 requests on the specified channel.
  1153.                 
  1154.                 which indicates the channel, and can take one of the 
  1155.                 following values:    
  1156.  
  1157.                 cmDataIn, cmDataOut, cmCntlIn, cmCntlOut, cmAttnIn, 
  1158.                 cmAttnOut.
  1159.  
  1160.  
  1161. Result Codes    cmGenericError, cmNoErr, cmRejected, cmFailed, cmNotOpen,
  1162.                 cmNotSupported.
  1163.  
  1164.  
  1165. æKY CMReset
  1166. æFa Connections.a 
  1167. æFc Connections.h 
  1168. æFp Connections.p 
  1169. æMM 
  1170. æTN $A08B A0^.w=$116 (or #278)
  1171. æDT CMReset(hConn: ConnHandle);
  1172. æC -----
  1173. Resetting the connection
  1174.  
  1175. Procedure        CMReset(hConn: ConnHandle);
  1176.  
  1177. Description:    CMReset causes the connection to be reset. The exact
  1178.                 state to which the    connection is reset depends upon the
  1179.                 connection protocol being implemented. The connection 
  1180.                 tool clears all local read and write buffers.
  1181.  
  1182. æKY CMBreak
  1183. æFa Connections.a 
  1184. æFc Connections.h 
  1185. æFp Connections.p 
  1186. æMM 
  1187. æTN $A08B A0^.w=$125 (or #293)
  1188. æDT CMBreak(hConn: ConnHandle; duration: LONGINT; async: BOOLEAN; completor: ProcPtr);
  1189. æC -----
  1190. Sending breaks
  1191.  
  1192. Procedure        CMBreak(hConn: ConnHandle; duration: LONGINT; async: 
  1193.                 BOOLEAN; completor: ProcPtr);
  1194.  
  1195. Description:    CMBreak effects a break operation upon the connection. 
  1196.                 The exact effect of this operation depends upon the tool
  1197.                 in use.
  1198.                 
  1199.                 duration specifies in ticks the length of the break.    
  1200.  
  1201.                 completor specifies the completion routine to be called
  1202.                 upon completion of the break. Completion routines are
  1203.                 called only after asynchronous calls to CMBreak. 
  1204.                 “Completion Routines,” later in this chapter, discusses
  1205.                 completion routines in more detail.
  1206.  
  1207.  
  1208. æKY CMGetConnEnvirons
  1209. æFa Connections.a 
  1210. æFc Connections.h 
  1211. æFp Connections.p 
  1212. æMM 
  1213. æTN $A08B A0^.w=$12C (or #300)
  1214. æDT CMGetConnEnvirons(hConn: ConnHandle; VAR theEnvirons: ConnEnvironRec): CMErr;
  1215. æC -----
  1216. Getting the connection environment
  1217.  
  1218. Function        CMGetConnEnvirons (hConn : ConnHandle; VAR theEnvirons :
  1219.                 ConnEnvironRec) : CMErr;
  1220.  
  1221. Description:    CMGetConnEnvirons provides a means for obtaining 
  1222.                 connection environment information.
  1223.                 
  1224.                 CMGetConnEnvirons returns the connection environment 
  1225.                 record in theEnvirons for the connection specified by 
  1226.                 ConnHandle. The connection tool is responsible for 
  1227.                 filling in each field of ConnEnvironRec with either a 
  1228.                 value (if it has a    valid value to supply) or 0.
  1229.                     The structure for version 0 of the connection 
  1230.                 environment record is as follows:
  1231.  
  1232.                 TYPE
  1233.                     ConnEnvironRecPtr            =    ^ConnEnvironRec;
  1234.                     ConnEnvironRec                =    RECORD;
  1235.                         version                    :    INTEGER;
  1236.                                     {version of this data structure}
  1237.                         baudRate                :    LONGINT;
  1238.                                     {data transfer rate}
  1239.                         dataBits                :    INTEGER;
  1240.                                     {number of significant bits per byte}
  1241.                         channels                :    CMChannel;
  1242.                                         {supported channels}
  1243.                         swFlowControl            :    BOOLEAN;
  1244.                                     {if software flow control is in use}
  1245.                         hwFlowControl            :    BOOLEAN;
  1246.                                     {if hardware flow control is in use}
  1247.                         flags                    :    CMFlags;
  1248.                     END;
  1249.     
  1250.                 The version field takes on the following value:    
  1251.         
  1252.                 CONST
  1253.                     curConnEnvRecVers            =    0;
  1254.  
  1255.                 The flags field of the ConnEnvironRec is a bit field 
  1256.                 with the following value:
  1257.  
  1258.                 TYPE
  1259.                     CMFlags                        =    INTEGER;
  1260.  
  1261.                 CONST
  1262.                     cmFlagsEOM                    =    $0001;
  1263.  
  1264.                 Other bits of flags are reserved by Apple Computer, Inc.    
  1265.  
  1266.                 channels is a bit field with the following values:    
  1267.  
  1268.                 TYPE
  1269.                     CMChannel                    =    INTEGER;
  1270.  
  1271.                 CONST
  1272.                     cmData                        =    $00000001;
  1273.                     cmCntl                        =    $00000002;
  1274.                     cmAttn                        =    $00000004;
  1275.  
  1276.                     cmDataClean                    =    $00000100;
  1277.                     cmCntlClean                    =    $00000200;
  1278.                     cmAttnClean                    =    $00000400;
  1279.  
  1280.                 Other bits of channels are reserved by Apple Computer,
  1281.                 Inc.    
  1282.  
  1283.  
  1284. Result Codes    cmGenericError, cmNoErr, cmNotSupported, envVersTooBig
  1285.  
  1286.  
  1287. æKY CMRead
  1288. æFa Connections.a 
  1289. æFc Connections.h 
  1290. æFp Connections.p 
  1291. æTN $A08B A0^.w=$111 (or #273)
  1292. æDT CMRead(hConn: ConnHandle; theBuffer: Ptr; VAR toRead: LONGINT; theChannel: CMChannel; async: BOOLEAN; completor: ProcPtr; timeout: LONGINT; VAR flags: CMFlags): CMErr;
  1293. æC -----
  1294. Reading data
  1295.  
  1296. Function        CMRead(hConn: ConnHandle; theBuffer: Ptr; VAR toRead: 
  1297.                 LONGINT; theChannel: CMChannel; async: BOOLEAN; 
  1298.                 completor: ProcPtr; timeout: LONGINT; VAR flags: 
  1299.                 CMFlags): CMErr;
  1300.  
  1301. Description:    CMRead reads data into a block of memory. Your 
  1302.                 application cannot queue multiple read requests for the
  1303.                 same channel on the same connection. However, your 
  1304.                 application can have both a pending read and a pending 
  1305.                 write on the same channel at the same time. Your 
  1306.                 application can call this routine at interrupt level.
  1307.                 
  1308.                 Note:     Your application should not check for an open 
  1309.                 channel prior to reading data. The connection tool might
  1310.                 be interpreting data locally and, therefore, not need an
  1311.                 open connection.
  1312.                 
  1313.                 theBuffer specifies the buffer to which the connection 
  1314.                 tool should read data. 
  1315.  
  1316.                 toRead specifies the number of bytes to be read. If your
  1317.                 application calls this routine synchronously, the 
  1318.                 connection tool returns the actual number of bytes it 
  1319.                 read in toRead. Your application can call CMStatus to 
  1320.                 see if an asynchronous read is pending. If your 
  1321.                 application calls this routine asynchronously, the 
  1322.                 asyncCount field of the connection record contains the 
  1323.                 actual number of bytes read when the connection tool 
  1324.                 calls the completion routine.
  1325.  
  1326.                 theChannel specifies the channel on which reading takes
  1327.                 place. Acceptable values are as follows:
  1328.  
  1329.                 CONST
  1330.                     cmData                        =    $00000001;
  1331.                     cmCntl                        =    $00000002;
  1332.                     cmAttn                        =    $00000004;
  1333.  
  1334.                 async specifies whether or not the request is 
  1335.                 asynchronous. If an asynchronous request is made, 
  1336.                 cmNoErr is returned immediately.     
  1337.  
  1338.                 completor specifies the completion routine to be called
  1339.                 upon completion of an asynchronous read request. 
  1340.                 Completion routines are discussed in greater detail 
  1341.                 later in this chapter in the section “Completion 
  1342.                 Routines.” 
  1343.  
  1344.                 timeout specifies a time period, in ticks, within which 
  1345.                 the connection tool must complete the read operation. If
  1346.                 it does not finish within the specified time, a timeout 
  1347.                 error occurs. For no timeout, use –1. If your 
  1348.                 application specifies 0, the connection tool reads as
  1349.                 many bytes, up to toRead bytes, as it    can in one read 
  1350.                 attempt. Some connection tools ignore this parameter.
  1351.  
  1352.                 flags indicates whether your application received an 
  1353.                 end-of-message indicator. If your application calls this
  1354.                 routine asynchronously, the connection tool returns the
  1355.                 end of message indicator in the reserved0 field of the
  1356.                 connection record when the completion routine is called.
  1357.  
  1358.                 CONST
  1359.                     cmFlagsEOM                    =    $0001;
  1360.  
  1361.  
  1362. Result Codes    cmGenericError, cmNoErr, cmRejected, cmFailed, cmTimeout, 
  1363.                 cmNotOpen, cmNoRequestPending, cmNotSupported.
  1364.  
  1365.  
  1366. æKY CMWrite
  1367. æFa Connections.a 
  1368. æFc Connections.h 
  1369. æFp Connections.p 
  1370. æTN $A08B A0^.w=$112 (or #274)
  1371. æDT CMWrite(hConn: ConnHandle; theBuffer: Ptr; VAR toWrite: LONGINT; theChannel: CMChannel; async: BOOLEAN; completor: ProcPtr; timeout: LONGINT; flags: CMFlags): CMErr;
  1372. æC -----
  1373. Writing data
  1374.  
  1375. Function        CMWrite(hConn: ConnHandle; theBuffer: Ptr; VAR toWrite: 
  1376.                 LONGINT; theChannel: CMChannel; async: BOOLEAN; 
  1377.                 completor: ProcPtr; timeout: LONGINT; flags: CMFlags):
  1378.                 CMErr;
  1379.  
  1380. Description:    CMWrite writes data from a block of memory. Your 
  1381.                 application cannot queue multiple write requests for the
  1382.                 same channel on the same connection. However, your 
  1383.                 application can have both a pending read and a pending 
  1384.                 write on the same channel at the same time. Your 
  1385.                 application can call this routine at interrupt level.
  1386.  
  1387.                 Note:     Your application should not check for an open 
  1388.                 channel prior to writing data. The connection tool might
  1389.                 be interpreting data locally and,therefore, not need an
  1390.                 open connection.
  1391.                 
  1392.                 theBuffer specifies the buffer from which the connection
  1393.                 gets the data to write.
  1394.  
  1395.                 toWrite specifies the number of bytes to be written. If 
  1396.                 your application calls this routine synchronously, the 
  1397.                 connection tool returns the actual number of bytes it 
  1398.                 wrote in toWrite. Your application can call CMStatus to 
  1399.                 see if an asynchronous write is pending. If your 
  1400.                 application calls this routine asynchronously, the 
  1401.                 asyncCount field of the connection record contains the 
  1402.                 actual number of bytes written when the completion 
  1403.                 routine is called.
  1404.  
  1405.                 theChannel specifies the channel on which writing takes
  1406.                 place. Acceptable values are as follows:
  1407.  
  1408.                 CONST
  1409.                     cmData                        =    $00000001;
  1410.                     cmCntl                        =    $00000002;
  1411.                     cmAttn                        =    $00000004;
  1412.  
  1413.                 async specifies whether or not the request is 
  1414.                 asynchronous. If your application makes an asynchronous
  1415.                 request, CMWrite returns cmNoErr immediately.        
  1416.  
  1417.                 completor specifies the completion routine to be called
  1418.                 upon completion of an asynchronous write request. 
  1419.                 Completion routines are discussed in greater detail 
  1420.                 later in this chapter in the section “Completion 
  1421.                 Routines.”
  1422.  
  1423.                 timeout specifies a time period, in ticks, within which
  1424.                 the connection tool must complete the write operation.
  1425.                 If it does not finish within thespecified period, a 
  1426.                 timeout error occurs. For no timeout, use –1. If your 
  1427.                 application specifies 0, the connection tool writes as
  1428.                 many bytes, up to toWrite bytes, as it can in one write
  1429.                 attempt. Some connection tools ignore this parameter.
  1430.  
  1431.                 flags indicates whether the connection tool should send
  1432.                 an end-of-message indicator. An end-of-message indicator
  1433.                 needs to be supported by the particular communications 
  1434.                 protocol being used; if an end-of-message indicator is
  1435.                 not supported by the connection protocol, your 
  1436.                 application should ignore this field.
  1437.  
  1438.                 CONST
  1439.                     cmFlagsEOM                    =    $0001;
  1440.  
  1441.  
  1442. Result Codes    cmGenericError, cmNoErr, cmRejected, cmFailed, cmTimeout, 
  1443.                 cmNotOpen, cmNoRequestPending, cmNotSupported.
  1444.  
  1445.  
  1446. æKY CMAddSearch
  1447. æFa Connections.a 
  1448. æFc Connections.h 
  1449. æFp Connections.p 
  1450. æMM 
  1451. æTN $A08B A0^.w=$126 (or #294)
  1452. æDT CMAddSearch(hConn: ConnHandle; theString: Str255; flags: CMSearchFlags; callBack: ProcPtr): LONGINT;
  1453. æC -----
  1454. Adding a data stream search
  1455.  
  1456. Function        CMAddSearch(hConn: ConnHandle; theString: Str255; flags:
  1457.                 CMSearchFlags; callBack: ProcPtr): LONGINT;
  1458.  
  1459. Description:    When an application is reading data with CMRead, you can
  1460.                 have the data stream searched for one or more patterns 
  1461.                 of bytes. To perform the search, your application must 
  1462.                 pass information to the Connection Manager, such as the
  1463.                 connection on which the data stream is coming in and the
  1464.                 sequence of bytes for which to look. CMAddSearch tells 
  1465.                 the Connection Manager to perform the search, passing it
  1466.                 search-specific information as well. Each time your 
  1467.                 application calls CMAddSearch, the Connection Manager 
  1468.                 searches for an additional sequence of bytes.
  1469.                 
  1470.                 The value CMAddSearch returns is a search reference 
  1471.                 number that is used by the CMRemoveSearch routine 
  1472.                 (described later in this section). If CMAddSearch 
  1473.                 returns –1, the connection tool did not successfully 
  1474.                 add the search. Your application uses the search 
  1475.                 reference number to distinguish among different searches
  1476.                 that may be occurring simultaneously on the same 
  1477.                 connection.
  1478.  
  1479.                 flags is a field that describes the search to be 
  1480.                 performed. The appropriate values are as follows:
  1481.  
  1482.                 TYPE
  1483.                     CMSearchFlags                    =    INTEGER;
  1484.  
  1485.                 CONST
  1486.                     cmSearchSevenBit                =    $0001;
  1487.  
  1488.                     If cmSearchSevenBit is on, the Connection Manager 
  1489.                 matches only the low 7 bits of a character; otherwise,
  1490.                 it matches all 8 bits. The other bits of flags are 
  1491.                 reserved by Apple Computer, Inc.
  1492.  
  1493.                 callBack is a pointer to a routine the Connection 
  1494.                 Manager will call during CMRead in the event that the 
  1495.                 connection tool finds a match. The calling conventions 
  1496.                 for the call-back procedure are given in the next 
  1497.                 section.
  1498.  
  1499.  
  1500. æKY MySearchCallBack
  1501. æDT MySearchCallBack(hConn: ConnHandle; matchPtr: Ptr; refNum: LONGINT);
  1502. æC -----
  1503. What to do when there's a match
  1504.  
  1505. Procedure        MySearchCallBack(hConn: ConnHandle; matchPtr: Ptr; 
  1506.                     refNum: LONGINT);
  1507.  
  1508. Description:    The Connection Manager will pass control to a search 
  1509.                 call-back procedure in the event that the connection 
  1510.                 tool finds a match in the incoming data stream. This 
  1511.                 routine may be called at interrupt level.
  1512.                 
  1513.                 matchPtr points to the last matched character in the 
  1514.                 read buffer.    
  1515.  
  1516.                 MySearchCallBack uses the search reference number 
  1517.                 CMAddSearch returns.        
  1518.  
  1519.                 Note:     The Connection Manager calls MySearchCallBack 
  1520.                 when a read is completed, and therefore might be called 
  1521.                 at interrupt level. If your application makes 
  1522.                 asynchronous calls, MySearchCallBack has the same 
  1523.                 restrictions as the standard Device Manager completion 
  1524.                 routines.
  1525.  
  1526.  
  1527. æKY CMRemoveSearch
  1528. æFa Connections.a 
  1529. æFc Connections.h 
  1530. æFp Connections.p 
  1531. æMM 
  1532. æTN $A08B A0^.w=$127 (or #295)
  1533. æDT CMRemoveSearch(hConn: ConnHandle; refNum: LONGINT);
  1534. æC -----
  1535. Stopping a data stream search
  1536.  
  1537. Procedure        CMRemoveSearch(hConn: ConnHandle; refNum: LONGINT);
  1538.  
  1539. Description:    CMRemoveSearch removes the search with the specified 
  1540.                 reference number for the specified connection record. 
  1541.                 This routine cannot be called at interrupt level (making
  1542.                 it impossible for MySearchCallBack to call this routine).    
  1543.  
  1544.                 refnum is the search reference number returned by 
  1545.                 CMAddSearch.        
  1546.  
  1547.  
  1548. æKY CMClearSearch
  1549. æFa Connections.a 
  1550. æFc Connections.h 
  1551. æFp Connections.p 
  1552. æMM 
  1553. æTN $A08B A0^.w=$128 (or #296)
  1554. æDT CMClearSearch(hConn: ConnHandle);
  1555. æC -----
  1556. Clearing all data stream searches
  1557.  
  1558. Procedure        CMClearSearch(hConn: ConnHandle);
  1559.  
  1560. Description:    CMClearSearch removes all searches associated with the 
  1561.                 specified connection record.
  1562.  
  1563.                 CMClearSearch cannot be called from interrupt level.    
  1564.  
  1565.  
  1566. æKY CMActivate
  1567. æFa Connections.a 
  1568. æFc Connections.h 
  1569. æFp Connections.p 
  1570. æMM 
  1571. æTN $A08B A0^.w=$113 (or #275)
  1572. æDT CMActivate(hConn: ConnHandle; activate: BOOLEAN);
  1573. æC -----
  1574. Activate events
  1575.  
  1576. Procedure        CMActivate(hConn: ConnHandle; activate: BOOLEAN);
  1577.  
  1578. Description:    CMActivate processes an activate or deactivate event 
  1579.                 (for instance, installing or removing a custom tool 
  1580.                 menu) for a window associated with the connection. 
  1581.  
  1582.                 If activate is TRUE, the connection tool processes the 
  1583.                 activate event.    Otherwise, it processes a deactivate 
  1584.                 event.
  1585.  
  1586.  
  1587. æKY CMResume
  1588. æFa Connections.a 
  1589. æFc Connections.h 
  1590. æFp Connections.p 
  1591. æMM 
  1592. æTN $A08B A0^.w=$114 (or #276)
  1593. æDT CMResume(hConn: ConnHandle; resume: BOOLEAN);
  1594. æC -----
  1595. Resume events
  1596.  
  1597. Procedure        CMResume(hConn: ConnHandle; resume: BOOLEAN);
  1598.  
  1599. Description:    CMResume processes a resume or suspend event for a 
  1600.                 window associated with the connection.
  1601.  
  1602.                 If resume is TRUE, the connection tool processes a 
  1603.                 resume event. Otherwise, it processes a suspend event.
  1604.  
  1605.  
  1606. æKY CMMenu
  1607. æFa Connections.a 
  1608. æFc Connections.h 
  1609. æFp Connections.p 
  1610. æMM 
  1611. æTN $A08B A0^.w=$115 (or #277)
  1612. æDT CMMenu(hConn: ConnHandle; menuID: INTEGER; item: INTEGER): BOOLEAN;
  1613. æC -----
  1614. Menu events
  1615.  
  1616. Function        CMMenu(hConn: ConnHandle; menuID: INTEGER; item:
  1617.                 INTEGER): BOOLEAN;
  1618.  
  1619. Description:    Your application must call CMMenu when the user chooses 
  1620.                 an item from a menu that is installed by the connection 
  1621.                 tool.
  1622.  
  1623.                 CMMenu returns FALSE if the connection tool did not 
  1624.                 handle the menu event.    
  1625.  
  1626.                 CMMenu returns TRUE if the connection tool did handle 
  1627.                 the menu event.        
  1628.  
  1629.  
  1630. æKY CMEvent
  1631. æFa Connections.a 
  1632. æFc Connections.h 
  1633. æFp Connections.p 
  1634. æMM 
  1635. æTN $A08B A0^.w=$12A (or #298)
  1636. æDT CMEvent(hConn: ConnHandle; theEvent: EventRecord);
  1637. æC -----
  1638. Other events
  1639.  
  1640. Procedure        CMEvent(hConn: ConnHandle; theEvent: EventRecord);
  1641.  
  1642. Description:    When your application receives an event, it should check
  1643.                 whether the refcon of the window is a tool’s ConnHandle.
  1644.                 Such an event occurs, for example, when the user clicks
  1645.                 a button in a dialog box displayed by the connection 
  1646.                 tool. If it does belong to a connection tool’s window, 
  1647.                 your application can call CMEvent. 
  1648.  
  1649.                 A window (or dialog box) created by a connection tool 
  1650.                 has a connection record    handle stored in the refCon 
  1651.                 field for windowRecord.        
  1652.  
  1653.  
  1654. æKY CMIntlToEnglish
  1655. æFa Connections.a 
  1656. æFc Connections.h 
  1657. æFp Connections.p 
  1658. æMM 
  1659. æTN $A08B A0^.w=$11E (or #286)
  1660. æDT MyCompletion(hConn: ConnHandle);
  1661. æC -----
  1662. Translating into English
  1663.  
  1664. Function         CMIntlToEnglish(hConn: ConnHandle; inputPtr: Ptr; 
  1665.                 VAR outputPtr: Ptr; language: INTEGER): OSErr;
  1666.  
  1667. Description:    CMIntlToEnglish converts a configuration string, which 
  1668.                 is pointed to by inputPtr, to an American English 
  1669.                 configuration string pointed to by outputPtr.    
  1670.  
  1671.                 The function returns an operating system error code if
  1672.                 any internal errors occur. The connection tool allocates
  1673.                 space for outputPtr. Your application is responsible for
  1674.                 disposing of the pointer with DisposPtr when done with 
  1675.                 it.
  1676.                     language specifies the language from which the 
  1677.                 string is to be    converted. Valid values for this field
  1678.                 are shown in the description of the Script Manager in 
  1679.                 Inside Macintosh, Volume V. If the language specified 
  1680.                 is not supported, this routine returns cmNoErr, but
  1681.                 outputPtr is NIL.            
  1682.  
  1683.  
  1684. æKY CMEnglishToIntl
  1685. æFa Connections.a 
  1686. æFc Connections.h 
  1687. æFp Connections.p 
  1688. æMM 
  1689. æTN $A08B A0^.w=$11F (or #287)
  1690. æDT CMEnglishToIntl(hConn: ConnHandle; inputPtr: Ptr; VAR outputPtr: Ptr; language: INTEGER): OSErr;
  1691. æC -----
  1692. Translating from English
  1693.  
  1694. Function        CMEnglishToIntl(hConn: ConnHandle; inputPtr: Ptr; VAR 
  1695.                 outputPtr: Ptr; language: INTEGER): OSErr;
  1696.  
  1697. Description:    CMEnglishToIntl converts an American English 
  1698.                 configuration string, which is pointed to by inputPtr, 
  1699.                 to a configuration string pointed to by outputPtr.
  1700.  
  1701.                 The function returns an operating system error code if 
  1702.                 any internal errors occur.    
  1703.                     The connection tool allocates space for outputPtr;
  1704.                 your application is responsible for disposing of the 
  1705.                 pointer with DisposPtr when done with it.    
  1706.                     language specifies the language to which the string 
  1707.                 is to be converted. Valid values for this field are 
  1708.                 shown in the description of the Script Manager in Inside
  1709.                 Macintosh, Volume V. If the language specified is not 
  1710.                 supported, cmNoErr is still returned, but outputPtr    is
  1711.                 NIL.    
  1712.  
  1713.  
  1714. æKY CMGetToolName
  1715. æFa Connections.a 
  1716. æFc Connections.h 
  1717. æFp Connections.p 
  1718. æMM 
  1719. æTN $A08B A0^.w=$106 (or #262)
  1720. æDT CMGetToolName(procID: INTEGER; VAR name: Str255);
  1721. æC -----
  1722. Getting the name of a tool
  1723.  
  1724. Procedure        CMGetToolName(procID: INTEGER; VAR name: Str255);
  1725.  
  1726. Description:    CMGetToolName returns in name the name of the tool 
  1727.                 specified by procID.
  1728.  
  1729.                 If procID references a connection tool that does not 
  1730.                 exist, the Connection Manager sets name to an empty 
  1731.                 string.    
  1732.  
  1733.  
  1734. æKY CMSetRefCon
  1735. æFa Connections.a 
  1736. æFc Connections.h 
  1737. æFp Connections.p 
  1738. æMM 
  1739. æTN $A08B A0^.w=$102 (or #258)
  1740. æDT CMSetRefCon(hConn: ConnHandle; refCon : LONGINT);
  1741. æC -----
  1742. Setting the connection record's reference constant
  1743.  
  1744. Procedure        CMSetRefCon(hConn: ConnHandle; refCon : LONGINT);
  1745.  
  1746. Description:    CMSetRefCon sets the connection record’s refCon field to
  1747.                 the specified value. It is very important that your 
  1748.                 application use this routine to change the value of the
  1749.                 reference constant, instead of changing it directly.
  1750.  
  1751.  
  1752. æKY CMGetRefCon
  1753. æFa Connections.a 
  1754. æFc Connections.h 
  1755. æFp Connections.p 
  1756. æMM 
  1757. æTN $A08B A0^.w=$103 (or #259)
  1758. æDT CMGetRefCon(hConn: ConnHandle): LONGINT;
  1759. æC -----
  1760. Getting the connection record's reference constant
  1761.  
  1762. Function        CMGetRefCon(hConn: ConnHandle): LONGINT;
  1763.  
  1764. Description:    CMGetRefCon returns the connection record’s reference 
  1765.                 constant.    
  1766.  
  1767.  
  1768. æKY CMSetUserData
  1769. æFa Connections.a 
  1770. æFc Connections.h 
  1771. æFp Connections.p 
  1772. æMM 
  1773. æTN $A08B A0^.w=$104 (or #260)
  1774. æDT CMSetUserData(hConn: ConnHandle; userData: LONGINT);
  1775. æC -----
  1776. Setting the userData field
  1777.  
  1778. Procedure        CMSetUserData(hConn: ConnHandle; userData: LONGINT);
  1779.  
  1780. Description:    CMSetUserData sets the connection record’s userData 
  1781.                 field to the specified value. It is very important that
  1782.                 your application use this routine to change the value of
  1783.                 the userData field, instead of changing it directly.    
  1784.  
  1785.  
  1786. æKY CMGetUserData 
  1787. æFa Connections.a 
  1788. æFc Connections.h 
  1789. æFp Connections.p 
  1790. æMM 
  1791. æTN $A08B A0^.w=$105 (or #261)
  1792. æDT CMGetUserData(hConn: ConnHandle): LONGINT;
  1793. æC -----
  1794. Getting the userData field
  1795.  
  1796. Function        CMGetUserData(hConn: ConnHandle): LONGINT;
  1797.  
  1798. Description:    CMGetUserData returns the connection record’s userData
  1799.                 field.        
  1800.  
  1801.  
  1802. æKY CMGetVersion 
  1803. æFa Connections.a 
  1804. æFc Connections.h 
  1805. æFp Connections.p 
  1806. æMM 
  1807. æTN $A08B A0^.w=$120 (or #288)
  1808. æDT CMGetVersion(hConn:ConnHandle): Handle;
  1809. æC -----
  1810. Getting 'vers' resource information
  1811.  
  1812. Function        CMGetVersion(hConn:ConnHandle): Handle;
  1813.  
  1814. Description:    CMGetVersion returns a handle to a relocatable block, 
  1815.                 which contains the information in the connection tool’s
  1816.                 'vers' resource with ID=1. Your    application is 
  1817.                 responsible for disposing of the handle when done with 
  1818.                 it.
  1819.  
  1820.                 Note:     The handle returned is not a resource handle.
  1821.  
  1822.  
  1823. æKY CMGetCMVersion
  1824. æFa Connections.a 
  1825. æFc Connections.h 
  1826. æFp Connections.p 
  1827. æMM 
  1828. æTN $A08B A0^.w=$121 (or #289)
  1829. æDT CMGetCMVersion: INTEGER;
  1830. æC -----
  1831. Getting the Conection Manager version number
  1832.  
  1833. Function        CMGetCMVersion: INTEGER;
  1834.  
  1835. Description:    CMGetCMVersion returns the version number of the 
  1836.                 Connection Manager.    
  1837.  
  1838.                 The version number of the Connection Manager described 
  1839.                 in this document is:    
  1840.  
  1841.                 CONST
  1842.                         curCMVersion                    =    1;
  1843.  
  1844.  
  1845. æKY MyCompletion
  1846. æDT MyCompletion(hConn: ConnHandle);
  1847. æC -----
  1848. Writing a completion routine
  1849.  
  1850. Procedure        MyCompletion(hConn: ConnHandle);
  1851.  
  1852. Description:    Completion routines have the same restrictions as do 
  1853.                 standard Device Manager completion routines. For 
  1854.                 example, your routines should not allocate memory. See 
  1855.                 the Device Manager chapters in Inside Macintosh for more
  1856.                 information.
  1857.  
  1858.                 When the Connection Manager calls MyCompletion, the 
  1859.                 errCode field of the connection record contains the 
  1860.                 appropriate error code. The asyncCount field of the 
  1861.                 connection record contains the actual number of bytes 
  1862.                 read or written. Because the errCode field of the 
  1863.                 connection record is used by all of the    Connection
  1864.                 Manager routines, it contains the error code for the 
  1865.                 asynchronous operation only during execution of 
  1866.                 MyCompletion.    
  1867.  
  1868.  
  1869. æKY Terminal Manager
  1870. æC -----
  1871. InitTM                            TMIdle
  1872. TMActivate                        TMIntlToEnglish
  1873. TMAddSearch                        TMKey
  1874. TMChoose                        TMMenu
  1875. TMClear                            TMNew
  1876. TMClearSearch                    TMPaint
  1877. TMClick                            TMRemoveSearch
  1878. TMCountTermKeys                    TMReset
  1879. TMDefault                        TMResize
  1880. TMDispose                        TMResume
  1881. TMDoTermKey                        TMScroll
  1882. TMEnglishToIntl                    TMSetConfig
  1883. TMEvent                            TMSetRefCon
  1884. TMGetConfig                        TMSetSelection
  1885. TMGetCursor                        TMSetupCleanup
  1886. TMGetIndTermKey                    TMSetupFilter
  1887. TMGetLine                        TMSetupItem
  1888. TMGetProcID                        TMSetupPostflight
  1889. TMGetRefCon                        TMSetupPreFlight
  1890. TMGetSelect                        TMSetupSetup
  1891. TMGetTermEnvirons                TMSetUserData
  1892. TMGetTMVersion                    TMStream
  1893. TMGetToolName                    TMUpdate
  1894. TMGetUserData                    TMValidate
  1895. TMGetVersion                    
  1896.  
  1897. TermRecord
  1898.  
  1899.  
  1900. æKY Terminals
  1901. æC -----
  1902. InitTM                            TMIdle
  1903. TMActivate                        TMIntlToEnglish
  1904. TMAddSearch                        TMKey
  1905. TMChoose                        TMMenu
  1906. TMClear                            TMNew
  1907. TMClearSearch                    TMPaint
  1908. TMClick                            TMRemoveSearch
  1909. TMCountTermKeys                    TMReset
  1910. TMDefault                        TMResize
  1911. TMDispose                        TMResume
  1912. TMDoTermKey                        TMScroll
  1913. TMEnglishToIntl                    TMSetConfig
  1914. TMEvent                            TMSetRefCon
  1915. TMGetConfig                        TMSetSelection
  1916. TMGetCursor                        TMSetupCleanup
  1917. TMGetIndTermKey                    TMSetupFilter
  1918. TMGetLine                        TMSetupItem
  1919. TMGetProcID                        TMSetupPostflight
  1920. TMGetRefCon                        TMSetupPreFlight
  1921. TMGetSelect                        TMSetupSetup
  1922. TMGetTermEnvirons                TMSetUserData
  1923. TMGetTMVersion                    TMStream
  1924. TMGetToolName                    TMUpdate
  1925. TMGetUserData                    TMValidate
  1926. TMGetVersion                    
  1927.  
  1928. TermRecord
  1929.  
  1930.  
  1931. æKY TermMgr
  1932. æC -----
  1933. InitTM                            TMIdle
  1934. TMActivate                        TMIntlToEnglish
  1935. TMAddSearch                        TMKey
  1936. TMChoose                        TMMenu
  1937. TMClear                            TMNew
  1938. TMClearSearch                    TMPaint
  1939. TMClick                            TMRemoveSearch
  1940. TMCountTermKeys                    TMReset
  1941. TMDefault                        TMResize
  1942. TMDispose                        TMResume
  1943. TMDoTermKey                        TMScroll
  1944. TMEnglishToIntl                    TMSetConfig
  1945. TMEvent                            TMSetRefCon
  1946. TMGetConfig                        TMSetSelection
  1947. TMGetCursor                        TMSetupCleanup
  1948. TMGetIndTermKey                    TMSetupFilter
  1949. TMGetLine                        TMSetupItem
  1950. TMGetProcID                        TMSetupPostflight
  1951. TMGetRefCon                        TMSetupPreFlight
  1952. TMGetSelect                        TMSetupSetup
  1953. TMGetTermEnvirons                TMSetUserData
  1954. TMGetTMVersion                    TMStream
  1955. TMGetToolName                    TMUpdate
  1956. TMGetUserData                    TMValidate
  1957. TMGetVersion                    
  1958.  
  1959. TermRecord
  1960.  
  1961. æKY TermRecord
  1962. æC -----
  1963.     TermHandle            =    ^TermPtr;
  1964.     TermPtr                =    ^TermRecord;
  1965.     TermRecord            =    RECORD
  1966.         procID            :    INTEGER;
  1967.         flags            :    TMFlags;
  1968.         errCode            :    TMErr;
  1969.         refCon            :    LONGINT;
  1970.         userData        :    LONGINT;
  1971.         defProc            :    ProcPtr;
  1972.         config            :    Ptr;
  1973.         oldConfig        :    Ptr;
  1974.         environsProc    :    ProcPtr;
  1975.         reserved1        :    LONGINT;
  1976.         reserved2        :    LONGINT;
  1977.         tmPrivate        :    Ptr;
  1978.         sendProc        :    ProcPtr;
  1979.         breakProc        :    ProcPtr;
  1980.         cacheProc        :    ProcPtr;
  1981.         clikLoop        :    ProcPtr;
  1982.         owner            :    WindowPtr;
  1983.         termRect        :    Rect;
  1984.         viewRect        :    Rect;
  1985.         visRect            :    Rect;
  1986.         lastIdle        :    LONGINT;
  1987.         selection        :    TMSelection;
  1988.         selType            :    TMSelTypes;
  1989.         mluField        :    LONGINT;
  1990.     END;
  1991.  
  1992. procID
  1993. procID is the terminal tool ID. This value is dynamically assigned by
  1994. the Terminal Manager when your application calls TMGetProcID.    
  1995.  
  1996.  
  1997. flags
  1998. flags is a bit field with the following masks:    
  1999.  
  2000.                 CONST
  2001.                         tmInvisible            =        $00000001;
  2002.                         tmSaveBeforeClear    =        $00000002;
  2003.                         tmNoMenus            =        $00000004;
  2004.                         tmAutoScroll        =        $00000008;
  2005.             
  2006.                 TYPE
  2007.                         TMFlags                :        LONGINT;
  2008.  
  2009.                     If your application sets tmInvisible, the Terminal
  2010.                 Manager maintains a terminal emulation but does not 
  2011.                 display it. Your application can use the terminal 
  2012.                 emulation and cache region to create some other 
  2013.                 presentation service, instead of a terminal emulation.
  2014.                     If your application sets tmSaveBeforeClear, the 
  2015.                 terminal tool will try to cache the entire terminal 
  2016.                 emulation region in response to any clear-screen 
  2017.                 operation. Clear-screen operations are generated from a 
  2018.                 user’s request, a clear-screen character sequence, or a
  2019.                 terminal-reset character sequence.
  2020.                     If your application sets tmNoMenus, the terminal
  2021.                 tool will not put up any custom menus.
  2022.                     If your application sets tmAutoScroll, the terminal
  2023.                 tool will automatically scroll the terminal emulation
  2024.                 window (if necessary) while the user is highlighting a 
  2025.                 selection.
  2026.  
  2027.  
  2028. errCode
  2029. The Terminal Manager does not use errCode; it is included in this 
  2030. version (version 1.0) of the terminal record for reasons of historical 
  2031. preservation. Your application must not use this field.
  2032.  
  2033.  
  2034. refCon
  2035. refCon is a LONGINT that your application can use.        
  2036.  
  2037.  
  2038. userData
  2039. userData is a LONGINT that your application can use.        
  2040.  
  2041.  
  2042. defProc
  2043. defProc is a pointer to the main code resource of the terminal tool 
  2044. that will implement the specifics of the terminal emulation. The 
  2045. terminal tool’s main code resource is of type 'tdef'.
  2046.  
  2047.  
  2048. config
  2049. config is a pointer to a data block that is private to the terminal 
  2050. tool. 
  2051.     Your application can store the contents of config to save the state 
  2052. of a terminal in a document. The structure, size, and contents of the 
  2053. configuration record are set by the tool. Your application can determine
  2054. the size of the configuration record by calling GetPtrSize, overwrite 
  2055. its contents using BlockMove, and validate the contents with TMValidate.    
  2056.     Your application can use TMGetConfig and TMSetConfig to manipulate 
  2057. fields in this record. For details, read “Interfacing with a Scripting
  2058. Language,” later in this chapter. Your application can save the state of
  2059. the terminal record by saving the string TMGetConfig returns. Also, your
  2060. application can restore the configuration of the terminal record by 
  2061. passing a saved string to TMSetConfig.    
  2062. You can find a description of config from a terminal tool perspective in
  2063. Chapter 8.    
  2064.  
  2065.  
  2066. oldConfig
  2067. oldConfig is a pointer to a data block that is private to the 
  2068. terminal tool and contains the most recently saved version of config.
  2069. Your application is responsible for setting    oldConfig when the user 
  2070. saves a session document.
  2071.  
  2072.  
  2073. environsProc
  2074. environsProc is a pointer to a routine in your application that the 
  2075. terminal tool can call to obtain a record describing the connection 
  2076. environment. A more detailed description of environsProc appears later 
  2077. in this chapter in “Routines That Must Be in Your Application.”
  2078.  
  2079.  
  2080. reserved1 and reserved2
  2081. reserved1 and reserved2 are reserved for the Terminal Manager. Your 
  2082. application    must not use this field.
  2083.  
  2084.  
  2085. tmPrivate
  2086. tmPrivate is a pointer to a data block that is private to the 
  2087. terminal tool. Your    application must not use this field.
  2088.  
  2089.  
  2090. sendProc
  2091. sendProc is a pointer to a routine your application calls when it
  2092. needs to send data to another application. A more detailed description 
  2093. of sendProc appears later in this chapter in “Routines That Must Be in 
  2094. Your Application.”
  2095.  
  2096.  
  2097. breakProc
  2098. breakProc is a pointer to a routine in your application that performs
  2099. a break    operation. The effect the break has depends on the terminal 
  2100. emulation being used. A more detailed description of breakProc appears
  2101. later in this chapter in “Routines That Must Be in Your Application.”
  2102.  
  2103.  
  2104. cacheProc
  2105. cacheProc is a pointer to a routine in your application that saves 
  2106. lines that scroll off the top of the terminal emulation region. The 
  2107. terminal tool also uses this routine to save the terminal screen before 
  2108. a clear-screen operation (if the TMSaveBeforeClear bit is set in the 
  2109. flags field of the terminal record). A more detailed description of    
  2110. cacheProc appears later in this chapter in “Routines That Must Be in 
  2111. Your Application.”
  2112.  
  2113.  
  2114. clikLoop
  2115. clikLoop is a pointer to a routine in your application that handles 
  2116. mouse clicks. The terminal tool calls the click loop repeatedly when the
  2117. user is clicking or dragging an object. A more detailed description of 
  2118. this routine appears later in this chapter in “Routines That Must Be in 
  2119. Your Application.”
  2120.  
  2121.  
  2122. owner
  2123. owner is a pointer to the grafPort in which your application displays
  2124. the terminal emulation.
  2125.  
  2126.  
  2127. termRect
  2128. termRect is the portRect of the current window, minus the scroll 
  2129. bars. This portRect    represent the boundaries of the terminal emulation 
  2130. region. Figure 4-3 shows how termRects relates to the terminal emulation
  2131. window.     
  2132.  
  2133.                 Note:     Your application can display the terminal 
  2134.                 emulation region in an area that is smaller than 
  2135.                 termRect, but it must not display the combination of the
  2136.                 cache region and terminal emulation region in an area 
  2137.                 larger than termRect.    
  2138.  
  2139.  
  2140. viewRect
  2141. viewRect is a rectangle, measured in pixels, that represents the 
  2142. screen of an actual    terminal. For some terminal types—for instance, 
  2143. Teletype or VT102™—    has    viewRect 24 lines and 80 columns. The dimensions
  2144. of viewRect remain constant except when    elements such as a tab ruler or
  2145. status bar appear in the terminal emulation window, or when the size of 
  2146. the display font changes. The relationship of termRect to viewRect        
  2147. determines how much of viewRect is visible in the terminal emulation 
  2148. window.    
  2149.     
  2150.  
  2151. visRect
  2152. visRect is a rectangle that represents the currently visible rows 
  2153. and columns in the terminal emulation region (for text terminals). 
  2154. Numbering of rows and columns begins with the number 1.
  2155.     visRect.top is the top visible line, and visRect.left is the 
  2156. leftmost visible column in the terminal emulation region. visRect.bottom
  2157. is the bottom visible line,    and    visRect.right is the rightmost visible 
  2158. column in the terminal region. These values are used by the application
  2159. to determine scroll-bar values.
  2160.  
  2161.  
  2162. lastIdle
  2163. lastIdle is the last time, in ticks, that the idle procedure was 
  2164. called for the specified terminal record.
  2165.  
  2166.  
  2167. selection
  2168. selection is a data structure that describes the extent of the 
  2169. current selection in the terminal emulation window. Since selection can 
  2170. describe either a rectangle or a region, it describes the selection in 
  2171. one of two kinds of data structures: a Rect    or a RgnHandle. The format 
  2172. of the TMSelection data structure is as follows:        
  2173.  
  2174. TYPE
  2175.         TMSelection                    =        RECORD
  2176.                 CASE INTEGER OF
  2177.                 1:    (
  2178.                     selRect            :        Rect;
  2179.                     );
  2180.                 2:    (
  2181.                     selRgnHandle    :        RgnHandle;
  2182.                     filler            :            LONGINT;
  2183.                     );
  2184.                 END;
  2185.                 
  2186.     selRect is of type Rect and describes the rectangle that has been 
  2187. selected. On a text    terminal, it contains the row/column pairs, with 
  2188. counting beginning at 1. On a graphics terminal, it contains pixel 
  2189. coordinates, with (1,1) being the topLeft corner of the    terminal region.
  2190.     On a graphics terminal, if the selection is a MacPaint-style lasso,
  2191. selection is a selRgnHandle that represents the selection region.
  2192.  
  2193.  
  2194. selType
  2195. selType is a field that further describes a selection; it indicates
  2196. the highlighting mode that is used to show the selection. Valid values
  2197. are as follows:
  2198.  
  2199. CONST
  2200.         selTextNormal            =        $0001;
  2201.         selTextBoxed            =        $0002;
  2202.         selGraphicsMarquee        =        $0004;
  2203.         selGraphicsLasso        =        $0008;
  2204.  
  2205. TYPE
  2206.  
  2207.  
  2208.         TMSelTypes                =        INTEGER;
  2209.  
  2210. selGraphicsMarquee is a standard rectangular MacPaint-style marquee.    
  2211. selGraphicsLasso is a standard MacPaint-style lasso. Your application 
  2212. uses these types of highlighting with graphics terminals.
  2213.  
  2214.  
  2215. mluField
  2216. mluField is a LONGINT that terminal tools use. Your application does
  2217. not need to be concerned with this field.
  2218.  
  2219.  
  2220. æKY InitTM
  2221. æFa Terminals.a 
  2222. æFc Terminals.h 
  2223. æFp Terminals.p 
  2224. æMM 
  2225. æTN $A08B A0^.w=$301 (or #769)
  2226. æDT InitTM: TMErr;
  2227. æC -----
  2228. Initializing the Terminal Manager
  2229.  
  2230. Function        InitTM: TMErr;
  2231.  
  2232. Description:    InitTM initializes the Terminal Manager. Your 
  2233.                 application should call this routine after it calls the 
  2234.                 standard Macintosh Toolbox initialization routines.
  2235.  
  2236.                 Warning        Your application must initialize the 
  2237.                 Communications Resource Manager (by calling    InitCRM) 
  2238.                 and then the Communications Toolbox Utilities 
  2239.                 (by calling InitCTBUtilities), whether or not it uses 
  2240.                 any of their calls, before it initializes the Terminal
  2241.                 Manager.      
  2242.  
  2243.                 InitTM returns an operating system error code if 
  2244.                 appropriate. Your application must check for the 
  2245.                 presence of the Communications Toolbox before calling 
  2246.                 this function. Sample code under “Determining Whether 
  2247.                 the Managers are Installed” in Appendix C shows you how
  2248.                 your application can make this check.
  2249.  
  2250. Result Codes    tmGenericError, tmNoErr, tmNoTools
  2251.  
  2252.  
  2253. æKY TMGetProcID
  2254. æFa Terminals.a 
  2255. æFc Terminals.h 
  2256. æFp Terminals.p 
  2257. æMM 
  2258. æTN $A08B A0^.w=$31F (or #799)
  2259. æDT TMGetProcID(name: Str255): INTEGER;
  2260. æC -----
  2261. Getting current procID information
  2262.  
  2263. Function        TMGetProcID(name: Str255): INTEGER;
  2264.  
  2265. Description:    Your application should call TMGetProcID just before 
  2266.                 creating a new terminal record, to find out the procID 
  2267.                 of a tool.    
  2268.  
  2269.                 name specifies a terminal tool. If a terminal tool is 
  2270.                 available with the specified name, its procID is 
  2271.                 returned. If name references a nonexistent terminal 
  2272.                 tool, TMGetProcID returns –1.    
  2273.  
  2274.  
  2275. æKY TMNew
  2276. æFa Terminals.a 
  2277. æFc Terminals.h 
  2278. æFp Terminals.p 
  2279. æMM 
  2280. æTN $A08B A0^.w=$302 (or #770)
  2281. æDT TMNew(termRect: Rect; viewRect: Rect; flags: TMFlags; procID: INTEGER; owner: WindowPtr; sendProc: ProcPtr; cacheProc: ProcPtr; breakProc: ProcPtr; clikLoop: ProcPtr; environsProc: ProcPtr; refCon: LONGINT; userData: LONGINT): TermHandle;
  2282. æC -----
  2283. Creating a terminal record
  2284.  
  2285. Function        TMNew(termRect: Rect; viewRect: Rect; flags: TMFlags; 
  2286.                 procID: INTEGER; owner: WindowPtr; sendProc: ProcPtr; 
  2287.                 cacheProc: ProcPtr; breakProc: ProcPtr; clikLoop: 
  2288.                 ProcPtr; environsProc: ProcPtr; refCon: LONGINT; 
  2289.                 userData: LONGINT): TermHandle;
  2290.  
  2291. Description:    Once the Terminal Manager has been initialized, your 
  2292.                 application needs to call TMNew to create a terminal 
  2293.                 record to describe the terminal emulation that is to 
  2294.                 take place. TMNew creates a new terminal record, fills 
  2295.                 in the fields it can, based on the parameters that were 
  2296.                 passed to it, and returns a handle to the new record in 
  2297.                 TermHandle. TMNew automatically makes two calls to 
  2298.                 TMDefault (which is described later in this chapter) to
  2299.                 fill in config and oldConfig. The Terminal    Manager then
  2300.                 loads the terminal tool’s main definition procedure, 
  2301.                 moves it high in the current heap, and locks it. If an
  2302.                 error occurs that prevents a new terminal record from
  2303.                 being created (for example, running out of memory),
  2304.                 TMNew passes back NIL in TermHandle.            
  2305.                     Your application must set the current port to the 
  2306.                 terminal window before it calls    TMNew.    
  2307.  
  2308.                 termRect is a rectangle in local coordinates that 
  2309.                 represents the boundaries of the terminal emulation 
  2310.                 region. Your application initially sets this value by 
  2311.                 passing it as a parameter to TMNew.    viewRect is a subset
  2312.                 of    termRect, which the terminal tool can actually write
  2313.                 into. Your application initially sets this value by
  2314.                 passing it as a parameter to TMNew, but the terminal 
  2315.                 tool may resize it.    
  2316.  
  2317.     flags is a bit field with the following masks:    
  2318.  
  2319.     CONST
  2320.         tmInvisible            =        $00000001;
  2321.         tmSaveBeforeClear    =        $00000002;
  2322.         tmNoMenus            =        $00000004;
  2323.         tmAutoScroll        =        $00000008;
  2324.  
  2325.         flags represents a request from your application for a level of 
  2326.     service.    
  2327.         Apple Computer, Inc. has reserved the bits of flags that are not
  2328.     shown in this document. Do not use them, or your code may not 
  2329.     work in the future.
  2330.         If your application sets tmInvisible, the Terminal Manager 
  2331.     maintains a    terminal emulation but does not display it. Your 
  2332.     application can use the terminal emulation and cache regions to 
  2333.     create some other presentation service instead of a terminal 
  2334.     emulation.
  2335.         If your application sets tmSaveBeforeClear, the terminal tool 
  2336.     attempts to    cache the entire terminal emulation region in response 
  2337.     to any clear-screen operation. Clear-screen operations are generated
  2338.     from either a user’s request, a clear-screen character sequence, or 
  2339.     a terminal-reset character sequence.
  2340.         If your application sets tmNoMenus, the terminal tool does not 
  2341.     display    any custom menus.
  2342.  
  2343.         If your application sets tmAutoScroll, the terminal tool 
  2344.     automatically scrolls the terminal emulation window (if necessary) 
  2345.     while the user highlights a selection.
  2346.  
  2347.     procID values are dynamically assigned by the Terminal Manager to 
  2348.     tools at run time. Applications should not store procID values in 
  2349.     “settings” files. Instead, they should store tool names, which can
  2350.     be converted to procID values with TMGetProcID. Use the ID that 
  2351.     TMGetProcID returns for procID.                
  2352.  
  2353.     owner is a pointer to the window in which your application is
  2354.     displaying the terminal emulation. If tmInvisible is FALSE, owner 
  2355.     should be a grafPort that the terminal tool has control over.
  2356.  
  2357.     sendProc is a pointer to a routine the terminal tool calls when it
  2358.     needs to send data on a connection. A more detailed description of 
  2359.     sendProc appears later in this chapter, in the section “Routines 
  2360.     That Must Be in Your Application.” 
  2361.     
  2362.     cacheProc is a pointer to a routine in your application that saves 
  2363.     lines that scroll off the top of the terminal emulation region. This
  2364.     routine also saves the terminal screen before a clear-screen 
  2365.     operation (if TMSaveBeforeClear is set). If your application does 
  2366.     not have a cacheProc, specify NIL in this field. A more detailed 
  2367.     description of cacheProc appears later in this chapter in the 
  2368.     section “Routines That Must Be in Your Application.”
  2369.  
  2370.     breakProc is a pointer to a routine in your application that 
  2371.     performs some sort of break operation. The effect the break has 
  2372.     depends upon the terminal emulation tool that your application is 
  2373.     using. A more detailed description of breakProc appears later in 
  2374.     this chapter in the section “Routines That Must Be in Your 
  2375.     Application.”
  2376.  
  2377.     clikLoop is a pointer to a routine in your application that is 
  2378.     called when the    mouse button is held down. The terminal tool calls 
  2379.     the click loop repeatedly when users are clicking and dragging the 
  2380.     mouse. A more detailed description of clikLoop appears later in this
  2381.     chapter, in the section “Routines That Must Be in Your Application.”
  2382.     Specify NIL in this field if your application has no clikLoop 
  2383.     procedure.
  2384.  
  2385.     environsProc is a pointer to a routine that the terminal tool calls 
  2386.     when it    requires information about the connection. See “Connection 
  2387.     Manager Routines” in Chapter 3 for information about the 
  2388.     CMGetConnEnvirons routine.    
  2389.  
  2390.     userData and refCon are fields your application can use.        
  2391.  
  2392.  
  2393. æKY TMDefault
  2394. æFa Terminals.a 
  2395. æFc Terminals.h 
  2396. æFp Terminals.p 
  2397. æMM 
  2398. æTN $A08B A0^.w=$315 (or #789)
  2399. æDT TMDefault(VAR theConfig: Ptr; procID: INTEGER; allocate: BOOLEAN);
  2400. æC -----
  2401. Initializing the terminal record
  2402.  
  2403. Procedure        TMDefault(VAR theConfig: Ptr; procID: INTEGER; allocate:
  2404.                 BOOLEAN);
  2405.  
  2406. Description:    TMDefault fills the configuration record pointed to by 
  2407.                 theConfig with the default configuration, which is 
  2408.                 specified by the terminal tool with the given procID. 
  2409.                 TMNew calls this procedure automatically when it fills
  2410.                 in the config and oldConfig fields in a new terminal 
  2411.                 record.    
  2412.  
  2413.                 If allocate is TRUE, the tool allocates space for 
  2414.                 theConfig in the current heap zone.
  2415.  
  2416.  
  2417. æKY TMValidate
  2418. æFa Terminals.a 
  2419. æFc Terminals.h 
  2420. æFp Terminals.p 
  2421. æMM 
  2422. æTN $A08B A0^.w=$314 (or #788)
  2423. æDT TMValidate(hTerm: TermHandle): BOOLEAN;
  2424. æC -----
  2425. Validating the terminal record
  2426.  
  2427. Function        TMValidate(hTerm: TermHandle): BOOLEAN;
  2428.  
  2429. Description:    TMValidate performs an internal consistency check on the
  2430.                 configuration and private data records of the terminal
  2431.                 record. TMNew and TMSetConfig call this routine after 
  2432.                 they have created a new terminal record, to make sure 
  2433.                 that the record contains values identical to those
  2434.                 specified by the terminal tool.
  2435.  
  2436.                 If the validation fails, the Terminal Manager returns 
  2437.                 TRUE and the terminal tool fills the configuration 
  2438.                 record with default values by calling TMDefault.    
  2439.                     Your application can call this routine after 
  2440.                 restoring a configuration, to verify that the terminal 
  2441.                 record contains the correct information, in a manner
  2442.                 similar to that shown next.
  2443.  
  2444.                 BlockMove(saveConfig,hTerm.config,
  2445.                     GetPtrSize(hTerm^^.config));
  2446.                 IF TMValidate(hTerm) THEN BEGIN
  2447.                     {validate failed}
  2448.                     END
  2449.                     ELSE BEGIN
  2450.                         {validate succeeded}
  2451.                         END
  2452.  
  2453.  
  2454. æKY TMChoose
  2455. æFa Terminals.a 
  2456. æFc Terminals.h 
  2457. æFp Terminals.p 
  2458. æMM 
  2459. æTN $A08B A0^.w=$32C (or #812)
  2460. æDT TMChoose(VAR hTerm: TermHandle; where: Point; idleProc: ProcPtr): INTEGER;
  2461. æC -----
  2462. Configuring a terminal tool
  2463.  
  2464. Function        TMChoose(VAR hTerm: TermHandle; where: Point; idleProc: 
  2465.                 ProcPtr): INTEGER;
  2466.  
  2467. Description:    An application can configure a terminal tool in one of 
  2468.                 three ways. The easiest and most straightforward way is 
  2469.                 by calling the TMChoose routine. This routine presents 
  2470.                 the user with a dialog box.
  2471.                     The second way an application can configure a 
  2472.                 terminal tool is by presenting the user with a custom 
  2473.                 tool-settings dialog box. This method is much more 
  2474.                 difficult and involves calling six routines. The 
  2475.                 routines are described in the next section, “Custom
  2476.                 Configuration of a Terminal Tool,” and “The Custom 
  2477.                 Tool-Settings Dialog Box” in Appendix C provides 
  2478.                 example code.
  2479.                     The third way your application can configure a
  2480.                 terminal tool is by using the scripting language 
  2481.                 interface, described in “Interfacing with a Scripting 
  2482.                 Language,” later in this chapter. This method allows 
  2483.                 your application to bypass user interface elements.
  2484.  
  2485.                 where is the point specified in global coordinates, 
  2486.                 where the upper-left corner    of the dialog box should 
  2487.                 appear. It is recommended that your application place
  2488.                 the dialog box as close to the upper-left corner of the 
  2489.                 screen as possible because the size of the dialog box 
  2490.                 varies from tool to tool.
  2491.  
  2492.                 idleProc is a procedure with no parameters that the 
  2493.                 Terminal Manager will automatically call every time    
  2494.                 TMChoose loops through the setup dialog box    filter 
  2495.                 procedure. Pass NIL if your application has no idleProc.         
  2496.  
  2497. TMChoose returns one of the following values:    
  2498.  
  2499. CONST
  2500.     chooseDisaster        =        -2;
  2501.     choose    Failed        =        -1;
  2502.     chooseOKMinor        =        1;
  2503.     chooseOKMajor        =        2;
  2504.     chooseCancel        =        3;
  2505.  
  2506.     chooseDisaster means that the TMChoose operation failed, destroyed 
  2507. the    terminal record, and returned NIL in the terminal handle.     
  2508.     chooseFailed means that the TMChoose operation failed and the 
  2509. terminal record was not changed.
  2510.     chooseOKMinor means that the user clicked OK in the dialog box, but
  2511. did    not change the terminal tool being used.
  2512.     chooseOKMajor means that the user clicked OK in the dialog box and 
  2513. also changed the terminal tool being used. The Terminal Manager then 
  2514. destroys the old terminal handle by calling TMDispose, and returns a new
  2515. terminal handle in hTerm.    
  2516.     chooseCancel means that the user clicked Cancel in the dialog box.    
  2517.  
  2518.  
  2519. æKY TMSetupPreflight
  2520. æFa Terminals.a 
  2521. æFc Terminals.h 
  2522. æFp Terminals.p 
  2523. æMM 
  2524. æTN $A08B A0^.w=$316 (or #790)
  2525. æDT TMSetupPreflight(procID: INTEGER; VAR magicCookie: LONGINT): Handle;
  2526. æC -----
  2527. Setting up the custom tool-settings dialog box
  2528.  
  2529. Function        TMSetupPreflight(procID: INTEGER; VAR magicCookie: 
  2530.                 LONGINT): Handle;
  2531.  
  2532. Description:    TMSetupPreflight returns a handle to a dialog item list 
  2533.                 that your application appends to the tool-settings 
  2534.                 dialog box. The handle comes from the terminal tool. 
  2535.                 (The calling application uses AppendDITL, which is 
  2536.                 discussed in Chapter 7.) This handle is not a resource 
  2537.                 handle. Your application is responsible for disposing of
  2538.                 the handle when done with it.
  2539.                     The terminal tool can use TMSetupPreflight to 
  2540.                 allocate a block of private    storage, and to store the 
  2541.                 pointer to that block in magicCookie. magicCookie should
  2542.                 be passed to the other routines that are used to set up
  2543.                 the custom tool-settings dialog box.
  2544.  
  2545.                 procID is the ID for the terminal tool that is being 
  2546.                 configured. Your application should get this value by 
  2547.                 using the TMGetProcID routine, which is    discussed 
  2548.                 earlier in this chapter.
  2549.                 
  2550.                 Note:     The refcon of the custom tool-settings dialog 
  2551.                 box should point to a data structure (an example of 
  2552.                 which is shown next) in which the first two bytes are
  2553.                 the tool procID and the next four bytes are magicCookie.
  2554.                 UserItem routines, for example, may require procID to 
  2555.                 obtain tool resources.    
  2556.  
  2557.  
  2558.                 TYPE
  2559.                     chooseDLOGdata        =    RECORD
  2560.                             procID        :    INTEGER
  2561.                             magicCookie    :    LONGINT
  2562.                 END;
  2563.  
  2564.  
  2565. æKY TMSetupSetup
  2566. æFa Terminals.a 
  2567. æFc Terminals.h 
  2568. æFp Terminals.p 
  2569. æMM 
  2570. æTN $A08B A0^.w=$317 (or #791)
  2571. æDT TMSetupSetup(procID: INTEGER; theConfig: Ptr; count: INTEGER; theDialog: DialogPtr; VAR magicCookie: LONGINT);
  2572. æC -----
  2573. Setting up the custom tool-settings dialog box items
  2574.  
  2575. Procedure        TMSetupSetup(procID: INTEGER; theConfig: Ptr; count: 
  2576.                 INTEGER; theDialog: DialogPtr; VAR magicCookie: 
  2577.                 LONGINT);
  2578.  
  2579. Description:    TMSetupSetup tells the terminal tool to set up controls
  2580.                 (like radio buttons or check boxes) in the dialog item 
  2581.                 list returned by TMSetupPreflight.    
  2582.  
  2583.                 procID is the ID for the terminal tool being configured.
  2584.                 Your application should use the same value for procID as
  2585.                 it passed to TMSetupPreflight.        
  2586.  
  2587.                 theConfig is a pointer to a configuration record for the
  2588.                 tool being configured.    
  2589.  
  2590.                 count is the number of the first item in the dialog item
  2591.                 list appended to the dialog box.
  2592.  
  2593.                 theDialog is the dialog box in which configuration is 
  2594.                 taking place.    
  2595.                 
  2596.                 magicCookie is a pointer to private storage for the terminal tool.    
  2597.  
  2598.  
  2599. æKY TMSetupFilter
  2600. æFa Terminals.a 
  2601. æFc Terminals.h 
  2602. æFp Terminals.p 
  2603. æMM 
  2604. æTN $A08B A0^.w=$318 (or #792)
  2605. æDT TMSetupFilter(procID: INTEGER; theConfig: Ptr; count: INTEGER; theDialog: DialogPtr; VAR theEvent: EventRecord; VAR theItem: INTEGER; VAR magicCookie: LONGINT): BOOLEAN;
  2606. æC -----
  2607. Filtering custom tool-settings dialog box events
  2608.  
  2609. Function        TMSetupFilter(procID: INTEGER; theConfig: Ptr; 
  2610.                 count:INTEGER; theDialog: DialogPtr; VAR theEvent: 
  2611.                 EventRecord; VAR theItem: INTEGER; VAR magicCookie:
  2612.                 LONGINT): BOOLEAN;
  2613.  
  2614. Description:    Your application calls TMSetupFilter as a filter 
  2615.                 procedure before it calls the standard modal dialog box
  2616.                 filter procedure for the custom tool-settings dialog box.
  2617.                 This routine allows terminal tools to filter events in 
  2618.                 the custom tool-settings dialog box.
  2619.  
  2620.                 procID is the ID for the terminal tool that is being
  2621.                 configured. Your application should use the same value 
  2622.                 for procID as it passed to TMSetupPreflight.    
  2623.  
  2624.                 theConfig is the pointer to the configuration record for
  2625.                 the tool being configured.
  2626.  
  2627.                 count is the number of the first item in the dialog item
  2628.                 list appended to the dialog box.
  2629.  
  2630.                 theDialog is the dialog box performing the configuration.    
  2631.  
  2632.                 theEvent is the event record for which filtering is to 
  2633.                 take place.    
  2634.  
  2635.                 theItem can return the item clicked in the dialog box.    
  2636.  
  2637.                 magicCookie is a pointer to private storage for the 
  2638.                 terminal tool.    
  2639.  
  2640.                 If the event passed in was handled, TMSetupFilter 
  2641.                 returns TRUE. Otherwise, FALSE indicates that your 
  2642.                 application should perform standard dialog box filtering.
  2643.                 
  2644.  
  2645. æKY TMSetupItem
  2646. æFa Terminals.a 
  2647. æFc Terminals.h 
  2648. æFp Terminals.p 
  2649. æMM 
  2650. æTN $A08B A0^.w=$319 (or #793)
  2651. æDT TMSetupItem(procID: INTEGER; theConfig: Ptr; count: INTEGER; theDialog: DialogPtr; VAR theItem: INTEGER; VAR magicCookie: LONGINT);
  2652. æC -----
  2653. Processing custom tool-settings dialog box events
  2654.  
  2655. Procedure        TMSetupItem(procID: INTEGER; theConfig: Ptr; count: 
  2656.                 INTEGER; theDialog: DialogPtr; VAR theItem: INTEGER; 
  2657.                 VAR magicCookie: LONGINT);
  2658.  
  2659. Description:    TMSetupItem processes events for controls in the custom 
  2660.                 tool-settings dialog box.
  2661.  
  2662.                 procID is the ID for the terminal tool being configured.
  2663.                 Your application should use the same value for procID as
  2664.                 it passed to TMSetupPreflight.        
  2665.  
  2666.                 theConfig is a pointer to the configuration record for 
  2667.                 the tool being configured.
  2668.  
  2669.                 count is the number of the first item in the dialog item
  2670.                 list appended to the dialog box.
  2671.  
  2672.                 theDialog is the dialog box performing the configuration.    
  2673.  
  2674.                 theItem is the item clicked in the dialog box. This 
  2675.                 value can be modified and sent back.
  2676.  
  2677.                 magicCookie is a pointer to private storage for the 
  2678.                 terminal tool.    
  2679.  
  2680.  
  2681. æKY TMSetupCleanup
  2682. æFa Terminals.a 
  2683. æFc Terminals.h 
  2684. æFp Terminals.p 
  2685. æMM 
  2686. æTN $A08B A0^.w=$31A (or #794)
  2687. æDT TMSetupCleanup(procID: INTEGER; theConfig: Ptr; count: INTEGER; theDialog: DialogPtr; VAR magicCookie: LONGINT);
  2688. æC -----
  2689. Performing clean-up operations
  2690.  
  2691. Procedure        TMSetupCleanup(procID: INTEGER; theConfig: Ptr; count: 
  2692.                 INTEGER; theDialog: DialogPtr; VAR magicCookie: 
  2693.                 LONGINT);
  2694.  
  2695. Description:    TMSetupCleanup disposes of any storage allocated in 
  2696.                 TMSetupPreflight and performs other clean-up operations.
  2697.                 If your application needs to shorten a dialog box, it 
  2698.                 should do so after calling this routine.
  2699.  
  2700.                 procID is the ID for the terminal tool that is being 
  2701.                 configured. Your application should use the same value 
  2702.                 for procID as it passed to TMSetupPreflight.    
  2703.  
  2704.                 theConfig is a pointer to the configuration record for 
  2705.                 the tool being configured.
  2706.  
  2707.                 count is the number of the first item in the dialog item
  2708.                 list appended to the dialog box.
  2709.  
  2710.                 theDialog is the dialog box performing the configuration.    
  2711.  
  2712.                 magicCookie is a pointer to private storage for the 
  2713.                 terminal tool.    
  2714.  
  2715.  
  2716. æKY TMSetupPostflight
  2717. æFa Terminals.a 
  2718. æFc Terminals.h 
  2719. æFp Terminals.p 
  2720. æMM 
  2721. æTN $A08B A0^.w=$331 (or #817)
  2722. æDT TMSetupPostflight(procID: INTEGER);
  2723. æC -----
  2724. Closing the tool file
  2725.  
  2726. Procedure        TMSetupPostflight(procID:INTEGER);
  2727.  
  2728. Description:    TMSetupPostflight closes the tool file if it is not 
  2729.                 being used by any session.    
  2730.  
  2731.                 procID is the ID for the terminal tool that is being 
  2732.                 configured. Your application should use the same value 
  2733.                 for procID as it passed to TMSetupPreflight.    
  2734.  
  2735.  
  2736. æKY TMGetConfig
  2737. æFa Terminals.a 
  2738. æFc Terminals.h 
  2739. æFp Terminals.p 
  2740. æMM 
  2741. æTN $A08B A0^.w=$31B (or #795)
  2742. æDT TMGetConfig(hTerm: TermHandle): Ptr;
  2743. æC -----
  2744. Getting the configuration string
  2745.  
  2746. Function        TMGetConfig(hTerm: TermHandle): Ptr;
  2747.  
  2748. Description:    TMGetConfig gets a configuration string from the 
  2749.                 terminal tool.    
  2750.  
  2751.                 TMGetConfig returns a null-terminated, C-style string 
  2752.                 from the terminal tool containing tokens that fully 
  2753.                 describe the configuration of the terminal record.
  2754.                 For an example, see the description of the next routine.
  2755.                 If an error occurs, TMGetConfig returns NIL.        
  2756.                     It is the responsibility of your application to
  2757.                 dispose of Ptr.    
  2758.  
  2759.  
  2760. æKY TMSetConfig
  2761. æFa Terminals.a 
  2762. æFc Terminals.h 
  2763. æFp Terminals.p 
  2764. æMM 
  2765. æTN $A08B A0^.w=$31C (or #796)
  2766. æDT TMSetConfig(hTerm: TermHandle; thePtr: Ptr): INTEGER;
  2767. æC -----
  2768. Setting the configuration with a string
  2769.  
  2770. Function        TMSetConfig(hTerm: TermHandle; thePtr: Ptr): INTEGER;
  2771.  
  2772. Description:    TMSetConfig passes a configuration string to the 
  2773.                 terminal tool.    
  2774.  
  2775.                 TMSetConfig passes a null-terminated, C-style string 
  2776.                 (see the example string    later in this section) to the 
  2777.                 terminal tool for parsing. The string is pointed to
  2778.                 by thePtr and must contain tokens that describe the 
  2779.                 configuration of the terminal record. The string can be
  2780.                 any length.
  2781.  
  2782.                     TMSetConfig ignores items it does not recognize or 
  2783.                 find relevant; such an occurrence causes the terminal 
  2784.                 tool to stop parsing the string and to return the
  2785.                 character position where the error occurred. If the 
  2786.                 terminal tool successfully parses the string, it returns
  2787.                 tmNoErr. If the terminal tool does not successfully    
  2788.                 parse the string, it returns one of the following values:
  2789.                 a number less than –1 to indicate an OSErr, –1 to 
  2790.                 indicate an unknown error, or a positive number to    
  2791.                 indicate the character position where parsing was 
  2792.                 stopped.
  2793.                     Individual terminal tools are responsible for the 
  2794.                 parsing operation.
  2795.  
  2796. Sample:            A null-terminated, C-style configuration string    
  2797.  
  2798.                 FontSize 9 Width 80 Cursor Underline Online True 
  2799.                 LocalEcho False AutoRepeat True RepeatControls False 
  2800.                 AutoWrap False NewLine False SmoothScroll False 
  2801.                 Transparent False SwapBSDelete False\0
  2802.  
  2803.  
  2804. æKY TMStream
  2805. æFa Terminals.a 
  2806. æFc Terminals.h 
  2807. æFp Terminals.p 
  2808. æMM 
  2809. æTN $A08B A0^.w=$30A (or #778)
  2810. æDT TMStream(hTerm: TermHandle; theBuffer: Ptr; theLength: LONGINT; flags: CMFlags): LONGINT;
  2811. æC -----
  2812. Putting data into the terminal
  2813.  
  2814. Function        TMStream(hTerm: TermHandle; theBuffer: Ptr; theLength: 
  2815.                 LONGINT; flags: CMFlags): LONGINT;
  2816.  
  2817. Description:    Your application should use TMStream to give the 
  2818.                 terminal tool data to write into the terminal emulation
  2819.                 buffer.
  2820.  
  2821.                 TMStream returns the number of bytes that it processed.    
  2822.  
  2823.                 theBuffer is the data that is either to be placed in the
  2824.                 terminal emulation buffer or processed by the terminal 
  2825.                 tool. Typically the data theBuffer points to has been 
  2826.                 provided by the connection tool your application is 
  2827.                 using.
  2828.  
  2829.                 CMFlags is described under the description of CMRead in 
  2830.                 Chapter 3.        
  2831.  
  2832.  
  2833. æKY TMPaint
  2834. æFa Terminals.a 
  2835. æFc Terminals.h 
  2836. æFp Terminals.p 
  2837. æMM 
  2838. æTN $A08B A0^.w=$306 (or #774)
  2839. æDT TMPaint(hTerm: TermHandle; theTermData:TermDataBlock; theRect: Rect);
  2840. æC -----
  2841. Drawing part of the terminal emulation region
  2842.  
  2843. Procedure        TMPaint(hTerm: TermHandle; theTermData:TermDataBlock; 
  2844.                 theRect: Rect);
  2845.  
  2846. Description:    TMPaint draws the data in theTermData into the rectangle
  2847.                 theRect, which is in local window coordinates.
  2848.  
  2849.                 theTermData.theData must be a handle to a block on the 
  2850.                 heap.    
  2851.  
  2852.  
  2853. æKY TMIdle
  2854. æFa Terminals.a 
  2855. æFc Terminals.h 
  2856. æFp Terminals.p 
  2857. æMM 
  2858. æTN $A08B A0^.w=$313 (or #787)
  2859. æDT TMIdle(hTerm: TermHandle);
  2860. æC -----
  2861. Providing necessary idle time
  2862.  
  2863. Procedure        TMIdle(hTerm: TermHandle);
  2864.  
  2865. Description:    Your application should call TMIdle at least once every
  2866.                 time it goes through its main event loop, so that the 
  2867.                 terminal tool can perform idle-loop tasks (like blinking
  2868.                 the cursor or searching the terminal emulation buffer).
  2869.  
  2870.                 hTerm specifies the terminal for which idle-loop tasks 
  2871.                 are to be performed.    
  2872.  
  2873.  
  2874. æKY TMGetLine
  2875. æFa Terminals.a 
  2876. æFc Terminals.h 
  2877. æFp Terminals.p 
  2878. æMM 
  2879. æTN $A08B A0^.w=$310 (or #784)
  2880. æDT TMGetLine(hTerm: TermHandle; lineNo: INTEGER; VAR theTermData:TermDataBlock);
  2881. æC -----
  2882. Getting lines from the terminal emulation buffer
  2883.  
  2884. Procedure        TMGetLine(hTerm: TermHandle; lineNo: INTEGER; VAR
  2885.                 theTermData:TermDataBlock);
  2886.  
  2887. Description:    TMGetLine returns a line from the terminal emulation 
  2888.                 buffer.    
  2889.  
  2890.                 lineNo specifies the line number of a line of data in 
  2891.                 the terminal emulation buffer. (Line numbering in the 
  2892.                 buffer begins with 1.)
  2893.  
  2894.                 Your application must allocate theTermData.theData with 
  2895.                 a length of 0. For example, theTermData.theData:=
  2896.                 NewHandle(0). The terminal tool copies the text into 
  2897.                 theTermData.theData, and increases the size of the 
  2898.                 handle if necessary. Your application is responsible for
  2899.                 disposing of theTermData.theData.    
  2900.  
  2901.  
  2902. æKY TMScroll
  2903. æFa Terminals.a 
  2904. æFc Terminals.h 
  2905. æFp Terminals.p 
  2906. æMM 
  2907. æTN $A08B A0^.w=$312 (or #786)
  2908. æDT TMScroll(hTerm: TermHandle; dH, dV: INTEGER);
  2909. æC -----
  2910. Scrolling the terminal emulation region
  2911.  
  2912. Procedure        TMScroll(hTerm: TermHandle; dH, dV: INTEGER);
  2913.  
  2914. Description:    TMScroll causes the terminal emulation region to scroll
  2915.                 horizontally, vertically, or both.
  2916.  
  2917.                 dH and dV specify the number of pixels to scroll
  2918.                 horizontally and vertically. If your application 
  2919.                 specifies positive values for dH and dV, the terminal        
  2920.                 emulation region scrolls down and to the right. If your 
  2921.                 application specifies negative values, the terminal 
  2922.                 emulation region scrolls up and to the left.
  2923.  
  2924.  
  2925. æKY TMClear
  2926. æFa Terminals.a 
  2927. æFc Terminals.h 
  2928. æFp Terminals.p 
  2929. æMM 
  2930. æTN $A08B A0^.w=$30D (or #781)
  2931. æDT TMClear(hTerm: TermHandle);
  2932. æC -----
  2933. Clearing the terminal emulation region
  2934.  
  2935. Procedure    TMClear(hTerm: TermHandle);
  2936.  
  2937. Description:    TMClear causes the terminal to clear the display screen
  2938.                 and to place the cursor in the home position. Nothing is
  2939.                 transmitted to the remote computer.
  2940.  
  2941.                 If the tmSaveBeforeClear flag is on in the terminal 
  2942.                 record, the terminal tool caches the data that is 
  2943.                 cleared from the terminal emulation region.
  2944.  
  2945.  
  2946. æKY TMReset
  2947. æFa Terminals.a 
  2948. æFc Terminals.h 
  2949. æFp Terminals.p 
  2950. æMM 
  2951. æTN $A08B A0^.w=$30C (or #780)
  2952. æDT TMReset(hTerm: TermHandle);
  2953. æC -----
  2954. Resetting the terminal
  2955.  
  2956. Procedure        TMReset(hTerm: TermHandle);
  2957.  
  2958. Description:    When your application calls TMReset, the terminal tool 
  2959.                 puts the specified terminal into a state that appears as
  2960.                 if the terminal had just been turned on. In actuality, 
  2961.                 the screen representation structure and internal state 
  2962.                 tables (if the tool has any) are reset to the values 
  2963.                 specified by the terminal tool, and the configuration
  2964.                 record for the terminal is reset to its last saved state.
  2965.  
  2966.                 If the tmSaveBeforeClear flag is on in the terminal 
  2967.                 record, the terminal tool caches the data that is 
  2968.                 cleared from the terminal emulation region prior to
  2969.                 resetting the terminal.
  2970.  
  2971.  
  2972. æKY TMResize
  2973. æFa Terminals.a 
  2974. æFc Terminals.h 
  2975. æFp Terminals.p 
  2976. æMM 
  2977. æTN $A08B A0^.w=$30E (or #782)
  2978. æDT TMResize(hTerm: TermHandle; newTermRect: Rect);
  2979. æC -----
  2980. Resizing the terminal region
  2981.  
  2982. Procedure        TMResize(hTerm: TermHandle; newTermRect: Rect);
  2983.  
  2984. Description:    TMResize resizes the terminal emulation region to the 
  2985.                 coordinates specified in newTermRect.    
  2986.  
  2987.                 newTermRect specifies bounds of the new termRect. The 
  2988.                 terminal tool automatically resizes the value of 
  2989.                 viewRect.    
  2990.  
  2991.  
  2992. æKY TMDispose
  2993. æFa Terminals.a 
  2994. æFc Terminals.h 
  2995. æFp Terminals.p 
  2996. æMM 
  2997. æTN $A08B A0^.w=$303 (or #771)
  2998. æDT TMDispose(hTerm: TermHandle);
  2999. æC -----
  3000. Disposing of a terminal record
  3001.  
  3002. Procedure        TMDispose(hTerm: TermHandle);
  3003.  
  3004.                 Important:    Your application must call TMDispose before 
  3005.                 disposing of the terminal emulation window with 
  3006.                 DisposeWindow. Since DisposeWindow clears all controls 
  3007.                 in the control list, a subsequent call to TMDispose may 
  3008.                 cause problems.      
  3009.  
  3010. Description:    TMDispose disposes of the terminal record and all 
  3011.                 associated data structures and controls.
  3012.                 
  3013.                 
  3014. æKY TMAddSearch
  3015. æFa Terminals.a 
  3016. æFc Terminals.h 
  3017. æFp Terminals.p 
  3018. æMM 
  3019. æTN $A08B A0^.w=$327 (or #807)
  3020. æDT TMAddSearch(hTerm: TermHandle; theString: Str255; where: Rect; searchType: TMSearchTypes; callBack: ProcPtr): INTEGER;
  3021. æC -----
  3022. Adding a data stream search
  3023.  
  3024. Function        TMAddSearch(hTerm: TermHandle; theString: Str255; where:
  3025.                 Rect; searchType: TMSearchTypes; callBack: ProcPtr): 
  3026.                 INTEGER;
  3027.  
  3028. Description:    TMAddSearch tells the terminal tool to search for a 
  3029.                 specified string.
  3030.  
  3031.                 If the search was successfully added, this function
  3032.                 returns the reference number assigned to the search. If 
  3033.                 the search was not successfully added, TMAddSearch 
  3034.                 returns –1. The tool searches for theString in the area
  3035.                 specified by where and within the selection specified by
  3036.                 searchType.     
  3037.  
  3038.                 where is a rectangle that contains two row/column pairs,
  3039.                 with row and column    numbers starting at 1.
  3040.                     By specifying a –1 as a value in the row/column 
  3041.                 pairs, your application can limit the search to one row,
  3042.                 one column, or the intersection of one row and one 
  3043.                 column. Table 4-1 shows how your application can use –1
  3044.                 as a search-area delimiter.
  3045.  
  3046. Table 4-1        TMAddSearch search-area delimiters    
  3047.  
  3048. ________________________________    ________________________________    
  3049. Area to search                        Row/column pair to use
  3050. ________________________________    ________________________________    
  3051. rectangle bounded by n,m,o,p        (n,m)    (o,p)
  3052. row n, any column                    (n,–1) (–1,–1)
  3053. any row, column m                    (–1,m) (–1,–1)
  3054. rows n - o (inclusive), any column    (n,–1) (o,–1)
  3055. column m - p (inclusive), any row    (–1,m) (–1,p)
  3056. anywhere (any row, any column)        (–1,–1) (–1,–1)
  3057. ________________________________    ________________________________    
  3058.  
  3059.  
  3060.                 Your application should pass in searchType the sum of 
  3061.                 three values that describes the search: searchNoDiacrit 
  3062.                 (to ignore diacritical marks), searchNoCase (to ignore 
  3063.                 case), and one of the constants that describes the    
  3064.                 selection.
  3065.  
  3066. Valid values are as follows:
  3067.  
  3068. TYPE
  3069.     TMSearchTypes                =        INTEGER;
  3070.  
  3071. CONST
  3072. {  search modifiers  }
  3073.     searchNoDiacrit                =        $0100;
  3074.     searchNoCase                =        $0200;
  3075.  
  3076. { constants that describe the selection }
  3077.     selTextNormal                =        $0001;
  3078.     selTextBoxed                =        $0002;
  3079.     selGraphicsMarquee            =        $0004;
  3080.     selGraphicsLasso            =        $0008;
  3081.  
  3082.                 callBack is a procedure that the tool automatically 
  3083.                 calls when it finds a match.    
  3084.                     callBack must be supplied by your application, and 
  3085.                 is described later in this chapter in the section 
  3086.                 “Routines That Must Be in Your Application.”
  3087.  
  3088.  
  3089. æKY TMRemoveSearch
  3090. æFa Terminals.a 
  3091. æFc Terminals.h 
  3092. æFp Terminals.p 
  3093. æMM 
  3094. æTN $A08B A0^.w=$328 (or #808)
  3095. æDT TMRemoveSearch(hTerm: TermHandle; refNum: INTEGER);
  3096. æC -----
  3097. Stopping a data stream search
  3098.  
  3099. Procedure        TMRemoveSearch(hTerm: TermHandle; refNum: INTEGER);
  3100.  
  3101. Description:    TMRemoveSearch stops the search specified by refNum.        
  3102.  
  3103.                 This routine cannot be called at interrupt level, but 
  3104.                 can be called by MyCallBack. (MyCallBack is discussed 
  3105.                 later in this chapter under “Routines That Must Be in 
  3106.                 Your Application.”)
  3107.  
  3108.  
  3109. æKY TMClearSearch
  3110. æFa Terminals.a 
  3111. æFc Terminals.h 
  3112. æFp Terminals.p 
  3113. æMM 
  3114. æTN $A08B A0^.w=$329 (or #809)
  3115. æDT TMClearSearch(hTerm: TermHandle);
  3116. æC -----
  3117. Clearing all data stream searches
  3118.  
  3119. Procedure        TMClearSearch(hTerm: TermHandle);
  3120.  
  3121. Description:    TMClearSearch stops all searches associated with the 
  3122.                 specified terminal record.
  3123.  
  3124.                 hTerm specifies the terminal record. TMClearSearch 
  3125.                 cannot be called from interrupt level.
  3126.  
  3127.  
  3128. æKY TMSetSelection
  3129. æFa Terminals.a 
  3130. æFc Terminals.h 
  3131. æFp Terminals.p 
  3132. æMM 
  3133. æTN $A08B A0^.w=$311 (or #785)
  3134. æDT TMSetSelection(hTerm: TermHandle; theSelection: TMSelection; selType: TMSelTypes);
  3135. æC -----
  3136. Setting and highlighting selections
  3137.  
  3138. Procedure        TMSetSelection(hTerm: TermHandle; theSelection: 
  3139.                 TMSelection; selType: TMSelTypes);
  3140.  
  3141. Description:    TMSetSelection makes theSelection the current selection.        
  3142.  
  3143.                 selType determines the type of highlighting for the 
  3144.                 selection. Valid values    are:
  3145.  
  3146.                 TYPE
  3147.                     TMSelTypes                =        INTEGER;
  3148.  
  3149.                 CONST
  3150.                     selTextNormal            =        $0001;
  3151.                     selTextBoxed            =        $0002;
  3152.                     selGraphicsMarquee        =        $0004;
  3153.                     selGraphicsLasso        =        $0008;
  3154.  
  3155.  
  3156. æKY TMGetSelect
  3157. æFa Terminals.a 
  3158. æFc Terminals.h 
  3159. æFp Terminals.p 
  3160. æMM 
  3161. æTN $A08B A0^.w=$30F (or #783)
  3162. æDT TMGetSelect(hTerm: TermHandle; theData: Handle; VAR theType: ResType): LONGINT;
  3163. æC -----
  3164. Getting data from a selection
  3165.     
  3166. Function        TMGetSelect(hTerm: TermHandle; theData: Handle; 
  3167.                 VAR theType: ResType): LONGINT;
  3168.  
  3169. Description:    TMGetSelect returns either the number of bytes in the 
  3170.                 selection, or an appropriate operating system error code.
  3171.  
  3172.                 If nothing is selected, TMGetSelect returns 0. 
  3173.                 Otherwise, it returns the size of the selected data.
  3174.  
  3175.                 theData must be a handle to a block of size 0. 
  3176.                 TMGetSelect will resize this block as necessary.
  3177.  
  3178.                 theType specifies the type of data this routine returns.
  3179.                 If theType is TEXT, theData is a handle to textual data.
  3180.                 theType and theData may be passed directly to the Scrap 
  3181.                 Manager.
  3182.  
  3183.  
  3184. æKY TMActivate
  3185. æFa Terminals.a 
  3186. æFc Terminals.h 
  3187. æFp Terminals.p 
  3188. æMM 
  3189. æTN $A08B A0^.w=$307 (or #775)
  3190. æDT TMActivate(hTerm: TermHandle; activate: BOOLEAN);
  3191. æC -----
  3192. Activate events
  3193.  
  3194. Procedure        TMActivate(hTerm: TermHandle; activate: BOOLEAN);
  3195.  
  3196. Description:    TMActivate processes an activate or deactivate event 
  3197.                 (for instance, installing or removing a custom tool 
  3198.                 menu) for a window associated with the terminal tool.
  3199.  
  3200.                 If activate is TRUE, the terminal tool processes an 
  3201.                 activate event. Otherwise, it processes a deactivate 
  3202.                 event.
  3203.  
  3204.  
  3205. æKY TMResume
  3206. æFa Terminals.a 
  3207. æFc Terminals.h 
  3208. æFp Terminals.p 
  3209. æMM 
  3210. æTN $A08B A0^.w=$308 (or #776)
  3211. æDT TMResume(hTerm: TermHandle; resume: BOOLEAN);
  3212. æC -----
  3213. Resume events
  3214.  
  3215. Procedure        TMResume(hTerm: TermHandle; resume: BOOLEAN);
  3216.  
  3217. Description:    TMResume processes a resume or suspend event for a 
  3218.                 terminal window. Resume and suspend events are processed
  3219.                 only if a tool has a custom menu to install or remove 
  3220.                 from the menu bar.
  3221.  
  3222.                 If resume is TRUE, then the terminal processes a resume
  3223.                 event. Otherwise, it processes a suspend event.
  3224.  
  3225.  
  3226. æKY TMMenu
  3227. æFa Terminals.a 
  3228. æFc Terminals.h 
  3229. æFp Terminals.p 
  3230. æMM 
  3231. æTN $A08B A0^.w=$30B (or #779)
  3232. æDT TMMenu(hTerm: TermHandle; menuID: INTEGER; item: INTEGER): BOOLEAN;
  3233. æC -----
  3234. Menu events
  3235.  
  3236. Function        TMMenu(hTerm: TermHandle; menuID: INTEGER; item: 
  3237.                 INTEGER): BOOLEAN;
  3238.  
  3239. Description:    Your application must call TMMenu when the user chooses
  3240.                 an item from a menu that is installed by the terminal 
  3241.                 tool.
  3242.  
  3243.                 TMMenu returns FALSE if the terminal tool did not handle
  3244.                 the menu event.    TMMenu returns TRUE if the terminal tool
  3245.                 did handle the menu event.        
  3246.  
  3247.  
  3248. æKY TMClick
  3249. æFa Terminals.a 
  3250. æFc Terminals.h 
  3251. æFp Terminals.p 
  3252. æMM 
  3253. æTN $A08B A0^.w=$309 (or #777)
  3254. æDT TMClick(hTerm: TermHandle; theEvent: EventRecord);
  3255. æC -----
  3256. Mouse events
  3257.  
  3258. Procedure        TMClick(hTerm: TermHandle; theEvent: EventRecord);
  3259.  
  3260. Description:    TMClick processes a mouseDown vent in the terminal 
  3261.                 emulation region. The routine pointed to by myclikLoop,
  3262.                 discussed later in this chapter in the section “Routines
  3263.                 That Must Be in Your Application,” is called repeatedly
  3264.                 by TMClick.    
  3265.  
  3266.  
  3267. æKY TMKey
  3268. æFa Terminals.a 
  3269. æFc Terminals.h 
  3270. æFp Terminals.p 
  3271. æMM 
  3272. æTN $A08B A0^.w=$304 (or #772)
  3273. æDT TMKey(hTerm: TermHandle; theEvent: EventRecord);
  3274. æC -----
  3275. Keyboard events
  3276.  
  3277. Procedure        TMKey(hTerm: TermHandle; theEvent: EventRecord);
  3278.  
  3279. Description:    TMKey processes a keyDown or autoKey event. The terminal
  3280.                 tool translates the keystroke into a sequence of bytes.
  3281.                 The terminal tool then calls your application’s sendProc
  3282.                 routine (discussed later in this chapter under “Routines
  3283.                 That Must Be in Your Application.”) to transmit this 
  3284.                 sequence of bytes.
  3285.  
  3286.                 Your application can create its own event record for 
  3287.                 specific keyboard events by filling in the event record
  3288.                 with the character code and –1 for the key code in the 
  3289.                 message field.
  3290.  
  3291.  
  3292. æKY TMUpdate
  3293. æFa Terminals.a 
  3294. æFc Terminals.h 
  3295. æFp Terminals.p 
  3296. æMM 
  3297. æTN $A08B A0^.w=$305 (or #773)
  3298. æDT TMUpdate(hTerm: TermHandle; visRgn: RgnHandle);
  3299. æC -----
  3300. Update events
  3301.  
  3302. Procedure        TMUpdate(hTerm: TermHandle; visRgn: RgnHandle);
  3303.  
  3304. Description:    Your application will typically call TMUpdate between 
  3305.                 BeginUpdate and EndUpdate.    
  3306.  
  3307.                 visRgn specifies the region to be updated.    
  3308.  
  3309.  
  3310. æKY TMEvent
  3311. æFa Terminals.a 
  3312. æFc Terminals.h 
  3313. æFp Terminals.p 
  3314. æMM 
  3315. æTN $A08B A0^.w=$32D (or #813)
  3316. æDT TMEvent(hTerm: TermHandle; theEvent: EventRecord);
  3317. æC -----
  3318. Other events
  3319.  
  3320. Procedure        TMEvent(hTerm: TermHandle; theEvent: EventRecord);
  3321.  
  3322. Description:    When your application receives an event, it should check
  3323.                 whether the refcon of the window is a tool’s hTerm. Such
  3324.                 an event occurs, for example, when the user clicks a
  3325.                 button in a dialog box displayed by the terminal tool. 
  3326.                 If it does belong to a terminal tool’s window, your 
  3327.                 application can call TMEvent.    
  3328.  
  3329.                 A window (or dialog box) created by a terminal tool has
  3330.                 a terminal record handle stored in the refCon field for 
  3331.                 windowRecord.        
  3332.  
  3333.  
  3334. æKY TMIntlToEnglish
  3335. æFa Terminals.a 
  3336. æFc Terminals.h 
  3337. æFp Terminals.p 
  3338. æMM 
  3339. æTN $A08B A0^.w=$31D (or #797)
  3340. æDT TMIntlToEnglish(hTerm: TermHandle; inputPtr: Ptr; VAR outputPtr: Ptr; language: INTEGER): OSErr;
  3341. æC -----
  3342. Translating into English
  3343.  
  3344. Function        TMIntlToEnglish(hTerm: TermHandle; inputPtr: Ptr; 
  3345.                 VAR outputPtr: Ptr; language: INTEGER): OSErr;
  3346.  
  3347. Description:    TMIntlToEnglish converts a configuration string, which 
  3348.                 is pointed to by inputPtr, to an American English 
  3349.                 configuration string pointed to by outputPtr.    
  3350.  
  3351.                 The function returns an operating system error code if 
  3352.                 any internal errors occur.    
  3353.                     The terminal tool allocates space for outputPtr. 
  3354.                 Your application should    dispose of this pointer when 
  3355.                 done with it.
  3356.                     language specifies the language from which the 
  3357.                 string is to be converted. Valid values for this field 
  3358.                 are shown in the description of the Script Manager in
  3359.                 Inside Macintosh, Volume V.    If the language specified is
  3360.                 not supported, this routine returns tmNoErr, but 
  3361.                 outputPtr is NIL.            
  3362.  
  3363.  
  3364. æKY TMEnglishToIntl
  3365. æFa Terminals.a 
  3366. æFc Terminals.h 
  3367. æFp Terminals.p 
  3368. æMM 
  3369. æTN $A08B A0^.w=$31E (or #798)
  3370. æDT TMEnglishToIntl(hTerm: TermHandle; inputPtr: Ptr; VAR outputPtr: Ptr; language: INTEGER): OSErr;
  3371. æC -----
  3372. Translate from English
  3373.  
  3374. Function        TMEnglishToIntl(hTerm: TermHandle; inputPtr: Ptr; 
  3375.                 VAR outputPtr: Ptr; language: INTEGER): OSErr;
  3376.  
  3377. Description:    TMEnglishToIntl converts an American English 
  3378.                 configuration string, which is pointed to by inputPtr, 
  3379.                 to a configuration string pointed to by    outputPtr.              
  3380.  
  3381.                 The function returns an operating system error code if 
  3382.                 any internal errors occur.    
  3383.                     The terminal tool allocates space for outputPtr. 
  3384.                 Your application is    responsible for disposing of the 
  3385.                 pointer with DisposPtr when done with it. 
  3386.                     language specifies the language to which the string 
  3387.                 is to be converted. Valid values for this field are 
  3388.                 shown in the description of the Script Manager in
  3389.                 Inside Macintosh, Volume V. If the language specified 
  3390.                 is not supported, tmNoErr is still returned, but 
  3391.                 outputPtr is NIL.        
  3392.  
  3393.  
  3394. æKY TMGetToolName
  3395. æFa Terminals.a 
  3396. æFc Terminals.h 
  3397. æFp Terminals.p 
  3398. æMM 
  3399. æTN $A08B A0^.w=$320 (or #800)
  3400. æDT TMGetToolName(procID: INTEGER; VAR name: Str255);
  3401. æC -----
  3402. Getting the name of a tool
  3403.  
  3404. Procedure        TMGetToolName(procID: INTEGER; VAR name: Str255);
  3405.  
  3406. Description:    TMGetToolName returns in name the name of the tool 
  3407.                 specified by procID.            
  3408.  
  3409.                 If procID references a terminal tool that does not 
  3410.                 exist, the Terminal    Manager sets name to an empty 
  3411.                 string.    
  3412.  
  3413.  
  3414. æKY TMSetRefCon
  3415. æFa Terminals.a 
  3416. æFc Terminals.h 
  3417. æFp Terminals.p 
  3418. æMM 
  3419. æTN $A08B A0^.w=$321 (or #801)
  3420. æDT TMSetRefCon(hTerm: TermHandle; refCon: LONGINT); 
  3421. æC -----
  3422. Setting the terminal tool's reference constant
  3423.  
  3424. Procedure        TMSetRefCon(hTerm: TermHandle; refCon: LONGINT); 
  3425.  
  3426. Description:    TMSetRefCon sets the terminal record’s refCon to the 
  3427.                 specified value. It is very important that your 
  3428.                 application use this routine to change the value of the 
  3429.                 reference constant, instead of changing it directly.
  3430.                 
  3431.  
  3432. æKY TMGetRefCon
  3433. æFa Terminals.a 
  3434. æFc Terminals.h 
  3435. æFp Terminals.p 
  3436. æMM 
  3437. æTN $A08B A0^.w=$322 (or #802)
  3438. æDT TMGetRefCon(hTerm: TermHandle): LONGINT;
  3439. æC -----
  3440. Getting the terminal tool's reference constant
  3441.  
  3442. Function        TMGetRefCon(hTerm: TermHandle): LONGINT;
  3443.  
  3444. Description:    TMGetRefCon returns the terminal record’s reference 
  3445.                 constant.    
  3446.  
  3447.  
  3448. æKY TMSetUserData 
  3449. æFa Terminals.a 
  3450. æFc Terminals.h 
  3451. æFp Terminals.p 
  3452. æMM 
  3453. æTN $A08B A0^.w=$323 (or #803)
  3454. æDT TMSetUserData(hTerm: TermHandle; userData: LONGINT);
  3455. æC -----
  3456. Setting the userData field
  3457.  
  3458. Procedure        TMSetUserData(hTerm: TermHandle; userData: LONGINT);
  3459.  
  3460. Description:    TMSetUserData sets the terminal record’s userData field 
  3461.                 to the value specified by userData. It is very important
  3462.                 that your application use this routine to change the 
  3463.                 value of the userData field, instead of changing it    
  3464.                 directly.
  3465.  
  3466.  
  3467. æKY TMGetUserData
  3468. æFa Terminals.a 
  3469. æFc Terminals.h 
  3470. æFp Terminals.p 
  3471. æMM 
  3472. æTN $A08B A0^.w=$324 (or #804)
  3473. æDT TMGetUserData(hTerm: TermHandle): LONGINT;
  3474. æC -----
  3475. Getting the userData field
  3476.  
  3477. Function        TMGetUserData(hTerm: TermHandle): LONGINT;
  3478.  
  3479. Description:    TMGetUserData returns the terminal record’s userData 
  3480.                 field.        
  3481.  
  3482.  
  3483. æKY TMGetVersion
  3484. æFa Terminals.a 
  3485. æFc Terminals.h 
  3486. æFp Terminals.p 
  3487. æMM 
  3488. æTN $A08B A0^.w=$325 (or #805)
  3489. æDT TMGetVersion(hTerm: TermHandle): Handle;
  3490. æC -----
  3491. Getting 'vers' resource information
  3492.  
  3493. Function        TMGetVersion(hTerm: TermHandle): Handle;
  3494.  
  3495. Description:    TMGetVersion returns a handle to a relocatable block 
  3496.                 that contains the information that is in the terminal 
  3497.                 tool’s 'vers' resource with ID=1. Your application is 
  3498.                 responsible for disposing of the handle when done with
  3499.                 it.
  3500.  
  3501.                 Note:     The handle returned is not a resource handle.    
  3502.  
  3503.  
  3504. æKY TMGetTMVersion
  3505. æFa Terminals.a 
  3506. æFc Terminals.h 
  3507. æFp Terminals.p 
  3508. æMM 
  3509. æTN $A08B A0^.w=$326 (or #806)
  3510. æDT TMGetTMVersion: INTEGER;
  3511. æC -----
  3512. Getting the Terminal Manager version number
  3513.  
  3514. Function        TMGetTMVersion: INTEGER;
  3515.  
  3516. Description:    TMGetTMVersion returns the version number of the 
  3517.                 Terminal Manager.    
  3518.  
  3519.                 The version number of the Terminal Manager described in
  3520.                 this document is:    
  3521.  
  3522.                 CONST
  3523.                     curTMVersion    =    1;
  3524.  
  3525.  
  3526. æKY TMGetCursor
  3527. æFa Terminals.a 
  3528. æFc Terminals.h 
  3529. æFp Terminals.p 
  3530. æMM 
  3531. æTN $A08B A0^.w=$32A (or #810)
  3532. æDT TMGetCursor(hTerm: TermHandle; cursType: TMCursorTypes): Point;
  3533. æC -----
  3534. Getting the current cursor position
  3535.  
  3536. Function        TMGetCursor(hTerm: TermHandle; cursType: TMCursorTypes):
  3537.                 Point;
  3538.  
  3539. Description:    TMGetCursor returns the current position of the cursor.
  3540.                 Numbering of rows and columns begins with 1.
  3541.  
  3542.                 Valid values for cursType are as follows:    
  3543.  
  3544.                 CONST        
  3545.                         cursorText            =        1;
  3546.                         cursorGraphics        =        2;
  3547.  
  3548.                 TYPE
  3549.  
  3550.                         TMCursorTypes        =        INTEGER;
  3551.  
  3552.                     For cursorText, the position returned is in 
  3553.                 row/column format, and for cursorGraphics the position 
  3554.                 is in pixel coordinates.    
  3555.  
  3556.  
  3557. æKY TMDoTermKey
  3558. æFa Terminals.a 
  3559. æFc Terminals.h 
  3560. æFp Terminals.p 
  3561. æMM 
  3562. æTN $A08B A0^.w=$32E (or #814)
  3563. æDT TMDoTermKey(hTerm: TermHandle; theKey: Str255): BOOLEAN;
  3564. æC -----
  3565. Emulating a special terminal key
  3566.  
  3567. Function        TMDoTermKey(hTerm: TermHandle; theKey: Str255): BOOLEAN;
  3568.  
  3569. Description:    TMDoTermKey emulates a special terminal key specified by
  3570.                 theKey.        
  3571.  
  3572.                 If the terminal tool does not understand the key 
  3573.                 specified by theKey, this routine returns FALSE. 
  3574.                 Otherwise, if the key specified is processed, this 
  3575.                 routine    returns TRUE.     
  3576.                     For information about the terminal keys supported by
  3577.                 a terminal tool, refer to that tool’s documentation.
  3578.  
  3579.                 This example shows how an application can use 
  3580.                 TMDoTermKey to emulate the user’s pressing a PF1 key:
  3581.  
  3582.                 IF TMDoTermKey(hTerm, 'PF1') THEN
  3583.                     BEGIN
  3584.                     END;
  3585.  
  3586.  
  3587. æKY TMCountTermKeys
  3588. æFa Terminals.a 
  3589. æFc Terminals.h 
  3590. æFp Terminals.p 
  3591. æMM 
  3592. æTN $A08B A0^.w=$32F (or #815)
  3593. æDT TMCountTermKeys(hTerm): INTEGER;
  3594. æC -----
  3595. Counting special terminal keys
  3596.  
  3597. Function        TMCountTermKeys(hTerm): INTEGER;
  3598.  
  3599. Description:    TMCountTermKeys returns the number of special terminal 
  3600.                 keys that the terminal tool supports.
  3601.  
  3602.                 TMCountTermKeys returns 0 if the terminal tool supports
  3603.                 no special terminal    keys.
  3604.  
  3605.  
  3606. æKY TMGetIndTermKey
  3607. æFa Terminals.a 
  3608. æFc Terminals.h 
  3609. æFp Terminals.p 
  3610. æMM 
  3611. æTN $A08B A0^.w=$330 (or #816)
  3612. æDT TMGetIndTermKey(hTerm:TermHandle; id:INTEGER; VAR theKey:Str255);
  3613. æC -----
  3614. Getting a terminal key
  3615.  
  3616. Procedure        TMGetIndTermKey(hTerm:TermHandle; id:INTEGER; 
  3617.                 VAR theKey:Str255);
  3618.  
  3619. Description:    TMGetIndTermKey returns the name of a specified key.    
  3620.  
  3621.                 TMGetIndTermKey returns in theKey the terminal key 
  3622.                 specified by id. If    id specifies a key that does not 
  3623.                 exist, this routine returns an empty string.
  3624.  
  3625.  
  3626. æKY TMGetTermEnvirons
  3627. æFa Terminals.a 
  3628. æFc Terminals.h 
  3629. æFp Terminals.p 
  3630. æMM 
  3631. æTN $A08B A0^.w=$32B (or #811)
  3632. æDT TMGetTermEnvirons(hTerm: TermHandle; VAR theEnvirons: TermEnvironRec): TMErr;
  3633. æC -----
  3634. Getting general terminal tool information
  3635.  
  3636. Function        TMGetTermEnvirons(hTerm: TermHandle; VAR theEnvirons:
  3637.                 TermEnvironRec): TMErr;
  3638.  
  3639. Description:    TMGetTermEnvirons returns theEnvirons, which reflects 
  3640.                 the internal conditions of the terminal tool. The caller
  3641.                 of this routine must fill in the version field of 
  3642.                 theEnvirons before calling TMGetTermEnvirons. 
  3643.  
  3644.                 This routine returns tmNoErr, envVersTooBig, or an 
  3645.                 operating system error code. The fields in theEnvirons 
  3646.                 are as follows:      
  3647.  
  3648.                 TYPE
  3649.                     TermEnvironPtr            =        ^TermEnvironRec;
  3650.                     TermEnvironRec            =        RECORD
  3651.                             version            :        INTEGER;
  3652.                             termType        :        TMTermTypes;
  3653.                             textRows        :        INTEGER;
  3654.                             textCols        :        INTEGER;
  3655.                             cellSize        :        Point;
  3656.                             graphicSize        :        Rect;
  3657.                             slop            :        Point;
  3658.                             auxSpace        :        Rect;
  3659.                     END;
  3660.  
  3661.  
  3662.                 version is the version number of the requested     terminal
  3663.                 environment record,    which is curTermEnvRecVers in this 
  3664.                 release of the Terminal Manager. The caller of the 
  3665.                 routine must fill in this field before calling 
  3666.                 TMGetTermEnvirons.         
  3667.  
  3668.                 termType is the type of terminal. termType can contain 
  3669.                 one or both of the following values:
  3670.  
  3671.                 CONST    
  3672.                     tmTextTerminal            =        $0001;
  3673.                     tmGraphicsTerminal        =        $0002;
  3674.  
  3675.                     curTermEnvRecVers        =        0;
  3676.  
  3677.                 TYPE
  3678.                     TMTermTypes                =        INTEGER;
  3679.  
  3680.                 textRows is the number of rows in the terminal emulation
  3681.                 region. The first row is row number 1.
  3682.  
  3683.                 textCols is the number of columns in the terminal 
  3684.                 emulation region. The first    column is column number 1.
  3685.  
  3686.                 cellSize is the height and width of each cell.    
  3687.  
  3688.                 graphicSize is the size of the default rectangle of the 
  3689.                 graphics terminal tool measured in pixels.
  3690.  
  3691.                 slop is the border of the terminal emulation region.    
  3692.  
  3693.                 auxSpace is a rectangle that specifies any additional 
  3694.                 space that is required at the top, bottom, right, or 
  3695.                 left of the terminal emulation region.
  3696.  
  3697. Result Codes    tmGenericError, tmNoErr, tmNotSupported, envVersTooBig.
  3698.  
  3699.  
  3700. æKY sendProc
  3701. æDT MySendProc(thePtr: Ptr; theSize: LONGINT; refCon: LONGINT; flags: CMFlags): LONGINT;
  3702. æC -----
  3703. Sending data out along the connection
  3704.  
  3705. Function        MySendProc (thePtr: Ptr; theSize: LONGINT; refCon:
  3706.                 LONGINT; flags: CMFlags): LONGINT;
  3707.  
  3708. Description:    When a tool needs to send data to another entity, it 
  3709.                 looks to your application to provide MySendProc. 
  3710.                 MySendProc may simply be the routine that the Connection
  3711.                 Manager uses to send data (as is the case in the next 
  3712.                 example), or it can be a routine that you have written.
  3713.  
  3714.                 thePtris a pointer to the data to be sent.     
  3715.  
  3716.                 theSize is the number of characters to be sent.    
  3717.  
  3718.                 refCon is the reference constant field for sending 
  3719.                 terminal’s terminal.    
  3720.  
  3721.                 MySendProc returns the actual number of characters sent.    
  3722.  
  3723.                 flags indicates whether the connection tool should send 
  3724.                 an end-of-message indicator. An end-of-message indicator
  3725.                 needs to be supported by the particular communications
  3726.                 protocol being used; if an end-of-message indicator is
  3727.                 not supported by the connection protocol, your 
  3728.                 application should ignore this field.
  3729.  
  3730.  
  3731. Sample routine for sending data
  3732. FUNCTION MySendProc(thePtr: Ptr;theSize: LONGINT;
  3733.                     refcon: LONGINT;flags: INTEGER): LONGINT;
  3734. VAR
  3735.     theErr:        CMErr;                { Any errors }
  3736.  
  3737. BEGIN
  3738.         MySendProc := 0;                { Assume the worst }
  3739.  
  3740.         IF gConn <> NIL THEN BEGIN
  3741.  
  3742.  
  3743.             { DO NOT check to see if the connection is first open before sending }
  3744.             { as the tool might be handling the data locally }
  3745.  
  3746.                                         { Send the data }
  3747.             theErr := CMWrite(gConn, thePtr, theSize, cmData, FALSE, NIL, 0, flags);
  3748.             IF (theErr = noErr) THEN
  3749.                 MySendProc := theSize    { If ok, we sent all }
  3750.             ELSE
  3751.                 ;                         { Handle errors }
  3752.         END; { Good Connection }
  3753.  
  3754. END; { MySendProc }
  3755.  
  3756.  
  3757. æKY MyBreakProc
  3758. æC -----
  3759. Sending a break
  3760.  
  3761. Procedure        MyBreakProc(duration: LONGINT; refCon: LONGINT);
  3762.  
  3763. Description:    Your application needs to contain information about how 
  3764.                 to send a break on a connection. Although it can contain
  3765.                 the code that performs the break operation, your 
  3766.                 application can also point to a connection tool routine 
  3767.                 that performs the break. This section gives an example.
  3768.  
  3769.                 duration specifies, in ticks, how long the break should
  3770.                 last. 
  3771.                 
  3772.                 refCon is the reference constant field of the terminal 
  3773.                 record.    
  3774.  
  3775. Sample showing how to break a connection
  3776.  
  3777. PROCEDURE MyBreakProc(duration: LONGINT; refcon : LONGINT);
  3778. BEGIN
  3779.         { Here we choose to issue a synchronous break }
  3780.         IF gConn <> NIL THEN
  3781.                 CMBreak(gConn, duration, FALSE, NIL);
  3782. END; { MyBreakProc }
  3783.  
  3784.  
  3785. æKY MyCacheProc
  3786. æC -----
  3787. Caching lines from the terminal region
  3788.  
  3789. Function        MyCacheProc(refCon: LONGINT; theTermData:TermDataBlock):
  3790.                 LONGINT;
  3791.  
  3792. Description:    Your application can cache lines that scroll off the top
  3793.                 of the terminal emulation region and, if desired, 
  3794.                 display them in the terminal emulation window. If you
  3795.                 want your application to display these lines, you have 
  3796.                 to provide the necessary code. If you do not want your 
  3797.                 application to display these lines, then your 
  3798.                 application should specify NIL for MyCacheProc when it 
  3799.                 calls TMNew.     
  3800.  
  3801.                 MyCacheProc must return tmNoErr if no error occurred 
  3802.                 during processing. Otherwise, it should return an 
  3803.                 appropriate error code.
  3804.  
  3805.                 refCon is the reference constant for the terminal record.    
  3806.  
  3807.                 theTermData is a data structure of type TermDataBlock:        
  3808.  
  3809.                 TYPE
  3810.                     TermDataBlockH        =        ^TermDataPtr;
  3811.                     TermDataBlockPtr    =    ^TermDataBlock;
  3812.                     TermDataBlock        =    RECORD
  3813.                         flags            :    TMTermTypes;
  3814.                         theData            :    Handle;
  3815.                         auxData            :    Handle;
  3816.                         reserved        :    LONGINT;
  3817.                 END;
  3818.  
  3819.                     theTerm.theData is a handle to a block on the heap. 
  3820.                 Your application can calculate the size of this block 
  3821.                 with GetHandleSize. Your application must copy any data 
  3822.                 it needs because theTermData belongs to the terminal 
  3823.                 tool and may not exist after MyCacheProc has finished. 
  3824.                 Your application can use HandToHand to copy the data.    
  3825.  
  3826. Sample showing how to cache lines
  3827.  
  3828. FUNCTION MyCacheProc    (refcon : LONGINT; theTermData : TermDataBlock )
  3829.         : LONGINT; 
  3830. VAR
  3831.         sizeCached    : LONGINT;
  3832.  
  3833. BEGIN
  3834.         { Check for data integrity }
  3835.         IF (theTermData.theData = NIL) THEN BEGIN
  3836.                 MyCacheProc := -1;
  3837.                 EXIT(MyCacheProc);
  3838.         END; { Bad Data }
  3839.  
  3840.         { Cache either graphics or text }
  3841.         HLock(theTermData.theData);
  3842.  
  3843.         { Get rid of the old cached data }
  3844.         IF (gCache <> NIL) THEN
  3845.                 DisposHandle(gCache);
  3846.  
  3847.         { make a copy of new text }
  3848.         gCache := theTermData.theData;
  3849.         IF (HandToHand(gCache) <> noErr) THEN BEGIN
  3850.                 gCache := NIL;    (* Handle errors *)
  3851.                 sizeCached := -1;
  3852.         END
  3853.         ELSE
  3854.                 sizeCached := GetHandleSize(gCache);
  3855.     
  3856.         HUnlock(theTermData.theData);
  3857.  
  3858.         IF (theTermData.flags = tmGraphicsTerminal) THEN BEGIN
  3859.                 { theTermData.theData is a handle to a QD Picture }
  3860.                 (*
  3861.                 Could save it as PICT
  3862.                 *)
  3863.         END { cache graphics }
  3864.         ELSE IF (theTermData.flags = tmTextTerminal) THEN BEGIN
  3865.                 { theTermData.theData is a handle to text }
  3866.                 
  3867.                 (*
  3868.                 Could write it out to the data fork
  3869.                 *)
  3870.         END; { cache text }
  3871.         MyCacheProc := sizeCached;
  3872. END; { MyCacheProc }
  3873.  
  3874.  
  3875. æKY MyCallBack
  3876. æC -----
  3877. Responding to a matched search parameter
  3878.  
  3879. Procedure        MyCallBack(hTerm: TermHandle; refNum: INTEGER; 
  3880.                 foundRect: Rect);
  3881.  
  3882. Description:    Your application can selectively filter data in the 
  3883.                 terminal emulation buffer by making use of a search 
  3884.                 call-back procedure. Since a tool will automatically
  3885.                 call MyCallBack when it finds a match to the search 
  3886.                 string, your application can respond in any way that you
  3887.                 want it to.
  3888.  
  3889.                 refNum is the reference number associated with a 
  3890.                 particular search. Reference numbers are assigned by the
  3891.                 Terminal Manager when a search is added to a terminal 
  3892.                 record with the TMAddSearch routine.    
  3893.  
  3894.                 foundRect describes in row/column format where the match
  3895.                 was found, with    row and column numbers starting at 1.
  3896.  
  3897.  
  3898. æKY MyClikLoop
  3899. æC -----
  3900. Responding to mouse clicks
  3901.  
  3902. Function        MyClikLoop(refCon: LONGINT): BOOLEAN;
  3903.  
  3904. Description:    This routine is called when the user is dragging the 
  3905.                 mouse in the terminal emulation window. Initially, your
  3906.                 application should process a mouse-down event by calling
  3907.                 TMClick, which in turn calls this routine.    
  3908.  
  3909.                 This routine returns TRUE when the mouse is clicked 
  3910.                 within the cache region. Otherwise, it returns FALSE.         
  3911.  
  3912.  
  3913. æKY environsProc
  3914. æC -----
  3915. Getting connection environment information
  3916.  
  3917. Function        MyEnvironsProc(refCon: LONGINT; VAR theEnvirons: 
  3918.                 ConnEnvironRec): CMErr;
  3919.  
  3920. Description:    To get information about the connection environment, the
  3921.                 terminal tool calls a routine in your application, 
  3922.                 MyEnvironsProc.     
  3923.  
  3924.                 refCon is the reference constant for the terminal tool.    
  3925.  
  3926.                 theEnvirons is a data structure containing the 
  3927.                 connection-environment record. Your application can 
  3928.                 either construct theEnvirons or use the Connection    
  3929.                 Manager routine CMGetConnEnvirons. For more information
  3930.                 about theEnvirons , see “CMGetConnEnvirons” in Chapter 3.        
  3931.                     The example that follows shows how MyEnvironsProc 
  3932.                 can point to a Connection Manager routine to retrieve 
  3933.                 information about the connection environment.
  3934.  
  3935. Sample terminal-environment routine
  3936.  
  3937. FUNCTION MyEnvironsProc(refCon: LONGINT;VAR theEnvirons: 
  3938.         ConnEnvironRec): OSErr;
  3939. BEGIN
  3940.         MyEnvironsProc:= envNotPresent;            { pessimism }
  3941.         theEnvirons.version := curConnEnvRecVers;    
  3942.                                                 { fill in version field }
  3943.  
  3944.                 IF (gConn <> NIL) THEN            { Tool sets the version }
  3945.                 MyEnvironsProc:= CMGetConnEnvirons(gConn,theEnvirons);
  3946.  
  3947. END; { MyEnvironsProc }
  3948.  
  3949.  
  3950. æKY File Transfer Manager
  3951. æC -----
  3952. FTAbort                            FTMenu
  3953. FTActivate                        FTNew
  3954. FTChoose                        FTResume
  3955. FTDefault                        FTSetConfig
  3956. FTDispose                        FTSetRefCon
  3957. FTEnglishToIntl                    FTSetupCleanup
  3958. FTEvent                            FTSetupFilter
  3959. FTExec                            FTSetupItem
  3960. FTGetConfig                        FTSetupPostFlight
  3961. FTGetFTVersion                    FTSetupPreFlight
  3962. FTGetProcID                        FTSetupSetup
  3963. FTGetRefCon                        FTSetUserData
  3964. FTGetToolName                    FTStart
  3965. FTGetUserData                    FTValidate
  3966. FTGetVersion                    InitFT
  3967. FTIntlToEnglish                    
  3968.  
  3969. FTRecord
  3970.  
  3971.  
  3972. æKY FileTransfers
  3973. æC -----
  3974. FTAbort                            FTMenu
  3975. FTActivate                        FTNew
  3976. FTChoose                        FTResume
  3977. FTDefault                        FTSetConfig
  3978. FTDispose                        FTSetRefCon
  3979. FTEnglishToIntl                    FTSetupCleanup
  3980. FTEvent                            FTSetupFilter
  3981. FTExec                            FTSetupItem
  3982. FTGetConfig                        FTSetupPostFlight
  3983. FTGetFTVersion                    FTSetupPreFlight
  3984. FTGetProcID                        FTSetupSetup
  3985. FTGetRefCon                        FTSetUserData
  3986. FTGetToolName                    FTStart
  3987. FTGetUserData                    FTValidate
  3988. FTGetVersion                    InitFT
  3989. FTIntlToEnglish                    
  3990.  
  3991. FTRecord
  3992.  
  3993.  
  3994. æKY FTMgr
  3995. æC -----
  3996. FTAbort                            FTMenu
  3997. FTActivate                        FTNew
  3998. FTChoose                        FTResume
  3999. FTDefault                        FTSetConfig
  4000. FTDispose                        FTSetRefCon
  4001. FTEnglishToIntl                    FTSetupCleanup
  4002. FTEvent                            FTSetupFilter
  4003. FTExec                            FTSetupItem
  4004. FTGetConfig                        FTSetupPostFlight
  4005. FTGetFTVersion                    FTSetupPreFlight
  4006. FTGetProcID                        FTSetupSetup
  4007. FTGetRefCon                        FTSetUserData
  4008. FTGetToolName                    FTStart
  4009. FTGetUserData                    FTValidate
  4010. FTGetVersion                    InitFT
  4011. FTIntlToEnglish                    
  4012.  
  4013. FTRecord
  4014.  
  4015.  
  4016. æKY FTRecord
  4017. æC -----
  4018.     FTHandle            =    ^FTPtr;
  4019.     FTPtr                =    ^FTRecord;
  4020.     FTRecord            =    PACKED RECORD
  4021.         procID            :    INTEGER;
  4022.         flags            :    FTFlags;
  4023.         errCode            :    FTErr;
  4024.         refCon            :    LONGINT;
  4025.         userData        :    LONGINT;
  4026.         defProc            :    ProcPtr;
  4027.         config            :    Ptr;
  4028.         oldConfig         :    Ptr;
  4029.         environsProc    :    ProcPtr;
  4030.         reserved1        :    LONGINT;        
  4031.         reserved2        :    LONGINT;        
  4032.         ftPrivate        :    Ptr;
  4033.         sendProc        :      ProcPtr;
  4034.         recvProc        :    ProcPtr;
  4035.         writeProc        :    ProcPtr;
  4036.         readProc        :    ProcPtr;
  4037.         owner            :    WindowPtr;
  4038.         direction        :    FTDirection;
  4039.         theReply        :     SFReply;
  4040.         writePtr        :    LONGINT;
  4041.         readPtr            :    LONGINT;
  4042.         theBuf            :    ^char;
  4043.         bufSize            :    LONGINT;
  4044.         autoRec            :    Str255;
  4045.         attributes        :    FTAttributes;
  4046.     END;
  4047.  
  4048. procID
  4049. procID is the file transfer tool ID. This value is dynamically 
  4050. assigned by the File Transfer Manager when your application calls 
  4051. FTGetProcID.    
  4052.  
  4053.  
  4054. flags
  4055. flags is a bit field that your application can use to determine when
  4056. a file transfer has    finished, and if the file transfer was successful. 
  4057. Valid values are as follows:
  4058.  
  4059. CONST
  4060.         ftIsFTMode        =        $00000001;
  4061.         ftNoMenus        =        $00000002;
  4062.         ftQuiet            =        $00000004;
  4063.         ftSucc            =        $00000080;
  4064.  
  4065. TYPE
  4066.         FTFlags            =        LONGINT;
  4067.  
  4068.     ftIsFTMode indicates whether a file transfer is in progress. A tool
  4069. turns this bit on just prior to performing the actual file transfer, and
  4070. turns it off when the file transfer stops.
  4071.     The file transfer tool will not display any custom menus if your 
  4072. application sets the ftNoMenus bit. The file transfer tool will not 
  4073. display any status dialog boxes or error alerts if your application sets
  4074. the ftQuiet bit. If your application turns ftQuiet on, it is responsible 
  4075. for displaying status dialog boxes and error alerts that the tool would
  4076. have displayed. Applications typically use these two bits to hide the 
  4077. file transfer tool from the user.
  4078.     ftSucc is a bit set by the file transfer tool when a file transfer
  4079. is completed successfully.
  4080.     Your application can first check to see if ftIsFTMode toggles from
  4081. on to off to find out when the file transfer has been completed. Then, 
  4082. it can check ftSucc to see if the file transfer was completed 
  4083. successfully.
  4084.     The other bits of flags are reserved by Apple Computer, Inc.      
  4085.  
  4086.  
  4087. errCode
  4088. errCode contains the last error reported to the File Transfer 
  4089. Manager. If errCode is negative, an operating system error occurred. If
  4090. errCode is positive, a File Transfer Manager error occurred. Valid 
  4091. values are as follows:
  4092.  
  4093. CONST
  4094.         ftGenericError        =        -1;
  4095.         ftNoErr                =        0;
  4096.         ftRejected            =        1;
  4097.         ftFailed            =        2;
  4098.         ftTimeOut            =        3;
  4099.         ftTooManyRetry        =        4;
  4100.         ftNotEnoughDspace    =        5;
  4101.         ftRemoteCancel        =        6;
  4102.         ftWrongFormat        =        7;
  4103.         ftNoTools            =        8;
  4104.         ftUserCancel        =        9;
  4105.         ftNotSupported        =        10;
  4106.  
  4107. TYPE
  4108.         FTErr                =        OSErr;
  4109.  
  4110.  
  4111. refCon
  4112. refCon is a four-byte field that your application can use.    
  4113.  
  4114.  
  4115. userData
  4116. userData is a four-byte field that your application can use.    
  4117.  
  4118.  
  4119. defProc
  4120. defProc is a pointer to the file transfer tool’s main definition 
  4121. procedure, which is contained in a code resource of type 'fdef'    .     
  4122.  
  4123.  
  4124. config
  4125. config is a pointer to a data block that is private to the file 
  4126. transfer tool. It can contain information like retry and timeout values,
  4127. but the contents vary from tool to tool.
  4128.     Your application can store the contents of config to save the state 
  4129. of a file transfer in a document. The structure, size, and contents of 
  4130. the configuration record are set by the tool. Your application can 
  4131. determine the size of the configuration record by calling GetPtrSize,     
  4132. overwrite its contents using BlockMove, and validate the contents with 
  4133. FTValidate.          
  4134.     Your application can use FTGetConfig and FTSetConfig to manipulate 
  4135. fields in this record. For details, read “Interfacing with a Scripting 
  4136. Language,” later in this chapter. Your application can save the state of
  4137. the file transfer record by saving the string FTGetConfig returns. Also,
  4138. your application can restore the configuration of the file transfer
  4139. record by passing a saved string to    FTSetConfig. You can find a 
  4140. description of config from a file transfer tool perspective in 
  4141. Chapter 8.
  4142.  
  4143.  
  4144. oldConfig
  4145. oldConfig is a pointer to a data block that is private to the file 
  4146. transfer tool and contains the most recently saved version of config. 
  4147. Your application is responsible for setting oldConfig when the user 
  4148. saves a session document.      
  4149.  
  4150.  
  4151. environsProc
  4152. environsProc is a pointer to a routine in your application that the 
  4153. file transfer tool calls to obtain a record describing the connection 
  4154. environment. For more information about environsProc, see 
  4155. “MyEnvironsProc Getting Connection Environment Information,” later in
  4156. this chapter.
  4157.  
  4158.  
  4159. reserved1 and reserved2          
  4160. reserved1 and reserved2 are fields reserved for the File Transfer 
  4161. Manager. Your application must not use this field.
  4162.  
  4163.  
  4164. ftPrivate
  4165. ftPrivate is a pointer to a data block that is private to the file 
  4166. transfer tool. Your application must not use this field.
  4167.  
  4168.  
  4169. sendProc
  4170. sendProc is a pointer to a routine that your application uses to send
  4171. data. This routine is discussed under “MySendProc Sending Data, ” later 
  4172. in this chapter.    
  4173.  
  4174.  
  4175. recvProc
  4176. recvProc is a pointer to a routine that your application uses to 
  4177. request data. This routine is discussed under “MyRecvProc Receiving 
  4178. Data,” later in this chapter.    
  4179.  
  4180.  
  4181. writeProc
  4182. writeProc is a pointer to a routine in your application that writes 
  4183. data to a file. If this    field is NIL, the file transfer tool performs
  4184. standard file operations (that is, writing to a disk). The file transfer
  4185. tool checks this field to see if your application has a writeProc 
  4186. routine. If it does, the tool lets writeProc handle writing data.           
  4187.     This routine can be used to perform postprocessing upon a file being
  4188. received, and is discussed under “MyWriteProc Writing Data,” later in 
  4189. this chapter.     
  4190.  
  4191.  
  4192. readProc
  4193. readProc is a pointer to a routine in your application that reads 
  4194. data from a file. If this field is NIL, the file transfer tool performs
  4195. standard file operations (that is, reading data from a disk). The file
  4196. transfer tool checks this field to see if your application has a 
  4197. readProc routine. If it does, the tool lets readProc handle reading data.
  4198.     This routine can be used to perform preprocessing upon a file being
  4199. sent, and is discussed under “MyReadProc Reading Data,” later in this
  4200. chapter.     
  4201.  
  4202.  
  4203. owner
  4204. owner is a pointer to a window (or grafPort) relative to which the 
  4205. file transfer status dialog box is positioned. If this field is    NIL, the
  4206. file transfer tool will not display a file transfer status dialog box.
  4207.  
  4208.  
  4209. direction
  4210. direction is a field that indicates whether a file is being sent to 
  4211. or received from another entity. Your application passes this field as a
  4212. parameter to FTStart (described later in this chapter). Valid values in
  4213. this field are as follows:
  4214.  
  4215. CONST
  4216.         ftReceiving            =        0;
  4217.         ftTransmitting        =        1;
  4218.         ftFullDuplex        =        2;
  4219.  
  4220. TYPE
  4221.         FTDirection            =        INTEGER;
  4222.  
  4223.  
  4224. theReply
  4225. theReply is an SFReply data structure. The SFReply data structure 
  4226. should contain the reference number of the working directory of the 
  4227. default volume for files being sent or received. If a file is being 
  4228. sent, the data structure should also contain the name of the file to be 
  4229. sent. If a file is being received and your application has information 
  4230. about the filename (for example, from a scripting language), the data 
  4231. structure should contain the filename to be used. Otherwise, pass an
  4232. empty string for theReply.filename.     
  4233.  
  4234.  
  4235. writePtr, readPtr, theBuf, and bufSize               
  4236. writePtr, readPtr, theBuf, and bufSize are properties of a particular 
  4237. file transfer tool.
  4238.  
  4239.  
  4240. autoRec
  4241. autoRec is a string that represents the start sequence a remote 
  4242. entity sends, causing the Macintosh to enter a file-reception mode. If 
  4243. this string is of length 0, remote-entity-initiated file transfers are
  4244. not supported by the file transfer tool. It is the application’s 
  4245. responsibility to make use of this field by searching the data stream 
  4246. for this sequence of characters. The Connection Manager, described in 
  4247. Chapter 3, provides routines that your application can use to search an
  4248. incoming data stream for a specified sequence of characters.
  4249.  
  4250.  
  4251. attributes
  4252. attributes is a field that describes the file transfer protocol 
  4253. supported by the file transfer tool. The bits in attributes are as 
  4254. follows:      
  4255.  
  4256. CONST
  4257.         ftSameCircuit            =        $0001;
  4258.         ftSendDisable            =        $0002;
  4259.         ftReceiveDisable        =        $0004;
  4260.         ftTextOnly                =        $0008;
  4261.  
  4262. TYPE
  4263.         FTAttributes            =        INTEGER
  4264.  
  4265.     ftSameCircuit indicates whether the file transfer tool creates its 
  4266. own data connection or expects the application to provide the 
  4267. connection. If this bit is set, the file transfer tool uses the data 
  4268. connection provided by the application. This bit is set by the file 
  4269. transfer tool.
  4270.     ftSendDisable indicates that the file transfer tool does not allow 
  4271. users to send files. Some tools that support sending files turn this bit 
  4272. on when they are in a mode that does not allow users to initiate sending
  4273. files. When this bit is on, your application should dim any menu items 
  4274. that allow users to send files.
  4275.     ftReceiveDisable indicates that the file transfer tool does not 
  4276. allow users to receive files. Some tools that support receiving files 
  4277. turn this bit on when they are in a mode that does not allow users to 
  4278. initiate receiving files. When this bit is on, your application should 
  4279. dim any menu items that allow users to receive files.
  4280.     ftTextOnly indicates that the file transfer tool sends and receives
  4281. only text files (files of type TEXT); the tool does not handle resource 
  4282. forks. The file transfer tool sets this bit.
  4283.     The other bits of this field are reserved by Apple Computer, Inc.
  4284.  
  4285.  
  4286. æKY InitFT
  4287. æFa FileTransfers.a 
  4288. æFc FileTransfers.h 
  4289. æFp FileTransfers.p 
  4290. æMM 
  4291. æTN $A08B A0^.w=$201 (or #513)
  4292. æDT InitFT: FTErr;
  4293. æC -----
  4294. Initializing the File Transfer Manager
  4295.  
  4296. Function        InitFT: FTErr;
  4297.  
  4298. Description:    InitFT initializes the File Transfer Manager. Your 
  4299.                 application must call this routine after calling the
  4300.                 standard Macintosh Toolbox initialization routines.
  4301.  
  4302.                 Warning:    Your application must initialize the 
  4303.                 Communications Resource Manager (by calling InitCRM) and
  4304.                 then the Communications Toolbox Utilities (by calling 
  4305.                 InitCTBUtilities), regardless of whether it uses any of 
  4306.                 their calls, before it initializes the File Transfer 
  4307.                 Manager.      
  4308.  
  4309.                 InitFT returns an operating system error code if 
  4310.                 appropriate.  Your application must check for the 
  4311.                 presence of the Communications Toolbox before calling 
  4312.                 this function. Sample code under “Determining Whether 
  4313.                 the Managers are Installed” in Appendix C shows you how
  4314.                 your application can make this check.
  4315.  
  4316. Result Codes    ftGenericError, ftNoErr, ftNoTools
  4317.  
  4318.  
  4319. æKY FTGetProcID
  4320. æFa FileTransfers.a 
  4321. æFc FileTransfers.h 
  4322. æFp FileTransfers.p 
  4323. æMM 
  4324. æTN $A08B A0^.w=$207 (or #519)
  4325. æDT FTGetProcID(name: Str255): INTEGER;
  4326. æC -----
  4327. Getting current procID information
  4328.  
  4329. Function        FTGetProcID(name: Str255): INTEGER;
  4330.  
  4331. Description:    Your application should call FTGetProcID just before 
  4332.                 creating a new file transfer record, to find out the 
  4333.                 procID of a tool.    
  4334.  
  4335.                 name specifies a file transfer tool. If a file transfer
  4336.                 tool is available with the specified name, its procID is
  4337.                 returned. If name refers to a nonexistent file transfer
  4338.                 tool, FTGetProcID returns –1.
  4339.  
  4340.  
  4341. æKY FTNew
  4342. æFa FileTransfers.a 
  4343. æFc FileTransfers.h 
  4344. æFp FileTransfers.p 
  4345. æMM 
  4346. æTN $A08B A0^.w=$208 (or #520)
  4347. æDT FTNew(procID: INTEGER; flags: FTFlags; sendProc: ProcPtr; recvProc: ProcPtr; readProc: ProcPtr; writeProc: ProcPtr; environsProc: ProcPtr;  owner: WindowPtr; refCon: LONGINT; userData: LONGINT): FTHandle;
  4348. æC -----
  4349. Creating a file transfer record
  4350.  
  4351. Function        FTNew(procID: INTEGER; flags: FTFlags; sendProc:
  4352.                 ProcPtr; recvProc: ProcPtr; readProc: ProcPtr; 
  4353.                 writeProc: ProcPtr; environsProc: ProcPtr;  owner: 
  4354.                 WindowPtr; refCon: LONGINT; userData: LONGINT): FTHandle;
  4355.  
  4356. Description:    Before your application can transfer files, it must 
  4357.                 create a file transfer record. FTNew creates a new file
  4358.                 transfer record, fills in the fields that it can, based
  4359.                 upon the parameters that were passed to it, and returns 
  4360.                 a handle to the new record in FTHandle. FTNew 
  4361.                 automatically makes two calls to FTDefault (described 
  4362.                 later in this chapter) to fill in config and oldConfig. 
  4363.                 The File Transfer Manager then loads the file transfer
  4364.                 tool’s main definition procedure, moves it high in the 
  4365.                 current heap, and locks it. If an error occurs that
  4366.                 prevents a new file transfer record from being created 
  4367.                 (for example, running out of memory), FTNew passes back 
  4368.                 NIL in FTHandle.             
  4369.  
  4370.                 procID specifies the file transfer tool the File 
  4371.                 Transfer Manager will use to transfer data.
  4372.  
  4373.                 flags is a bit field with the following masks:    
  4374.  
  4375.                 CONST
  4376.                     ftIsFTMode        =        $0001;
  4377.                     ftNoMenus        =        $0002;
  4378.                     ftQuiet            =        $0004;
  4379.                     ftSucc            =        $0080;
  4380.  
  4381.                 TYPE
  4382.                     FTFlags            =        LONGINT;
  4383.  
  4384.                     flags represents a request from your application for
  4385.                 a level of service.    Your application can set only two of
  4386.                 these bits, ftNoMenus and ftQuiet. If your application 
  4387.                 sets ftNoMenus, the file transfer tool will not display
  4388.                 any    custom menus. If your application sets ftQuiet, the
  4389.                 file transfer tool will not display any windows.
  4390.                 Applications typically use these bits to hide the file
  4391.                 transfer tool from the user.
  4392.                     Apple Computer, Inc. has reserved the bits of flags 
  4393.                 that are not shown in this document. Do not use them, or
  4394.                 your code may not work in the future.
  4395.                     ftSucc is a bit that is set by the file transfer 
  4396.                 tool when a file transfer is completed successfully. 
  4397.                 Your application should not set this bit.
  4398.                     Your application can check to see if ftIsFTMode 
  4399.                 toggles from on to off to find out when the file 
  4400.                 transfer has been completed. Then it can check ftSucc to
  4401.                 see if the file transfer was completed successfully.
  4402.  
  4403.                 sendProc is a pointer to a routine that the application
  4404.                 uses to send data.    
  4405.  
  4406.                 recvProc is a pointer to a routine that the application 
  4407.                 uses to request data.    
  4408.  
  4409.                 readProc is a pointer to a routine in your application 
  4410.                 that reads data from a file. The file transfer tool 
  4411.                 checks this field to see if your application has a 
  4412.                 readProc routine. If it does, the tool lets readProc
  4413.                 handle reading data. If NIL, the file transfer tool 
  4414.                 performs standard file operations (that is, reading    data
  4415.                 from a disk).
  4416.                     This function can be used to perform preprocessing 
  4417.                 upon a file being sent, and is discussed later in this 
  4418.                 chapter, in “Routines Your Application Provides.”
  4419.  
  4420.                 writeProc is a pointer to a routine in your application 
  4421.                 that writes data to a file. The file transfer tool 
  4422.                 checks this field to see if your application has a 
  4423.                 writeProc routine. If it does, the tool lets  
  4424.                 writeProc handle writing data. If NIL, the file 
  4425.                 transfer tool performs standard file operations 
  4426.                 (that is, writing to a disk).
  4427.                     This function can be used to perform post-processing
  4428.                 upon a file being received, and is discussed later in 
  4429.                 this chapter, in “Routines Your Application Provides.”
  4430.  
  4431.                 environsProc is a pointer to a routine that the file 
  4432.                 transfer tool can call when    it wants to get information 
  4433.                 about the connection. See Chapter 3 for more information
  4434.                 about the CMGetConnEnvirons routine.     
  4435.  
  4436.                 owner is a pointer to a window, relative to which the 
  4437.                 file transfer status dialog    box is positioned. If this 
  4438.                 field is NIL, the File Transfer Manager will not display
  4439.                 a file transfer status dialog box.
  4440.  
  4441.                 refCon and userData    are fields that your application can
  4442.                 use.         
  4443.  
  4444.  
  4445. æKY FTDefault
  4446. æFa FileTransfers.a 
  4447. æFc FileTransfers.h 
  4448. æFp FileTransfers.p 
  4449. æMM 
  4450. æTN $A08B A0^.w=$210 (or #528)
  4451. æDT FTDefault(VAR theConfig: Ptr; procID: INTEGER; allocate: BOOLEAN);
  4452. æC -----
  4453. Initializing the file transfer record
  4454.  
  4455. Procedure        FTDefault(VAR theConfig: Ptr; procID: INTEGER; allocate:
  4456.                 BOOLEAN);
  4457.  
  4458. Description:    FTDefault fills the specified configuration record with 
  4459.                 the default configuration specified by the file transfer
  4460.                 tool. FTNew calls this procedure automatically when it 
  4461.                 fills in the config and oldConfig fields in a new file 
  4462.                 transfer record.
  4463.  
  4464.                 If allocate is TRUE, the tool allocates space for 
  4465.                 theConfig in the current heap zone.
  4466.  
  4467.  
  4468. æKY FTValidate
  4469. æFa FileTransfers.a 
  4470. æFc FileTransfers.h 
  4471. æFp FileTransfers.p 
  4472. æMM 
  4473. æTN $A08B A0^.w=$20F (or #527)
  4474. æDT FTValidate(hFT: FTHandle): BOOLEAN;
  4475. æC -----
  4476. Validating the file transfer record
  4477.  
  4478. Function        FTValidate(hFT: FTHandle): BOOLEAN;
  4479.  
  4480. Description:    FTValidate performs an internal consistency check on the
  4481.                 configuration and private data records of the file 
  4482.                 transfer record. FTNew and FTSetConfig call this routine
  4483.                 after they have created a new file transfer record, to 
  4484.                 make sure that the the record contains values identical 
  4485.                 to those specified by the file transfer tool.
  4486.  
  4487.                 If the validation fails, the File Transfer Manager returns 
  4488.                 TRUE and the file transfer tool fills the configuration 
  4489.                 record with default values by calling FTDefault.    
  4490.                     Your application can call this routine after 
  4491.                 restoring a configuration, to verify that the file 
  4492.                 transfer record contains the correct information, in a 
  4493.                 manner similar to that shown next.
  4494.  
  4495.                 BlockMove(saveConfig,hFT^^.config,
  4496.                         GetPtrSize(hFT^^.config));
  4497.                 IF FTValidate(hFT) THEN BEGIN
  4498.                     { validate failed }
  4499.                     END
  4500.                     ELSE BEGIN
  4501.                         { validate succeeded }
  4502.                         END
  4503.                         
  4504.  
  4505. æKY FTChoose
  4506. æFa FileTransfers.a 
  4507. æFc FileTransfers.h 
  4508. æFp FileTransfers.p 
  4509. æMM 
  4510. æTN $A08B A0^.w=$21C (or #540)
  4511. æDT FTChoose(VAR hFt:FTHandle; where: Point; idleProc: ProcPtr): INTEGER;
  4512. æC -----
  4513. Configuring a file transfer tool
  4514.  
  4515. Function        FTChoose(VAR hFt:FTHandle; where: Point; idleProc: 
  4516.                 ProcPtr): INTEGER;
  4517.  
  4518. Description:    An application can configure a file transfer tool in one
  4519.                 of three ways. The easiest and most straightforward way
  4520.                 is by calling the FTChoose routine. This routine 
  4521.                 presents the user with a dialog box. 
  4522.                     The second way an application can configure a file 
  4523.                 transfer tool is by presenting the user with a custom 
  4524.                 tool-settings dialog box. This method is much more 
  4525.                 difficult and involves calling six routines. The 
  4526.                 routines are described in the next section, “Custom 
  4527.                 Configuration of a File Transfer Tool,” and “The Custom
  4528.                 Tool-Settings Dialog Box” in Appendix C provides example
  4529.                 code.
  4530.                     The third way your application can configure a file
  4531.                 transfer tool is by using the scripting language 
  4532.                 interface, described under “Interfacing with a Scripting
  4533.                 Language,” later in this chapter. This method allows 
  4534.                 your application to bypass user interface elements.
  4535.  
  4536.                 where is the point, specified in global coordinates, 
  4537.                 where the upper-left corner of the dialog box should 
  4538.                 appear. It is recommended that your application place 
  4539.                 the dialog box as close as possible to the upper-left 
  4540.                 corner of the screen, because the size of the dialog box
  4541.                 varies from tool to tool. 
  4542.                 
  4543.                 idleProc is a procedure with no parameters that the File
  4544.                 Transfer Manager will automatically call every time 
  4545.                 FTChoose loops through the setup dialog    filter procedure.
  4546.                 Pass NIL if your application has no idleProc.        
  4547.  
  4548.                 FTChoose returns one of the following values:     
  4549.  
  4550.                 CONST
  4551.                     chooseDisaster            =        -2;
  4552.                     chooseFailed            =        -1;
  4553.                     chooseOKMinor            =        1;
  4554.                     chooseOKMajor            =        2;
  4555.                     chooseCancel            =        3;
  4556.  
  4557.                     chooseDisaster means that the FTChoose operation 
  4558.                 failed, destroyed the file transfer record, and returned
  4559.                 NIL in the file transfer handle.    
  4560.  
  4561.                     chooseFailed means that the    operation FTChoose 
  4562.                 failed and the file    transfer record was not changed.
  4563.  
  4564.                     chooseOKMinor means that the user clicked OK in the 
  4565.                 dialog box, but did    not change the file transfer tool 
  4566.                 being used.
  4567.  
  4568.                     chooseOKMajor means that the user clicked OK in the
  4569.                 dialog box and also    changed the file transfer tool being
  4570.                 used. The old file transfer handle is destroyed by the
  4571.                 File Transfer Manager, by calling FTDispose. The file 
  4572.                 transfer is closed down, all pending read and write 
  4573.                 operations are terminated, and a new file transfer 
  4574.                 handle is returned in hFT.    
  4575.  
  4576.                     chooseCancel means that the user clicked Cancel in 
  4577.                 the dialog box.    
  4578.  
  4579.  
  4580. æKY FTSetupPreflight
  4581. æFa FileTransfers.a 
  4582. æFc FileTransfers.h 
  4583. æFp FileTransfers.p 
  4584. æMM 
  4585. æTN $A08B A0^.w=$211 (or #529)
  4586. æDT FTSetupPreflight(procID: INTEGER; VAR magicCookie: LONGINT): Handle;
  4587. æC -----
  4588. Setting up the tool-settings dialog box
  4589.  
  4590. Function        FTSetupPreflight(procID: INTEGER; VAR magicCookie: 
  4591.                 LONGINT): Handle;
  4592.  
  4593. Description:    FTSetupPreflight returns a handle to a dialog item list
  4594.                 that your application appends to the tool-settings 
  4595.                 dialog box. The handle comes from the file transfer 
  4596.                 tool. (The calling application uses AppendDITL, 
  4597.                 discussed in Chapter 7.) This handle is not a resource 
  4598.                 handle. Your application is responsible for disposing of
  4599.                 the handle when done with it.
  4600.                     The file transfer tool can use FTSetupPreflight to 
  4601.                 allocate a block of private storage, and to store the 
  4602.                 pointer to that block in magicCookie. magicCookie should
  4603.                 be passed to the other routines that are used to set up
  4604.                 the tool-settings dialog box.
  4605.  
  4606.                 procID is the ID for the file transfer tool that is 
  4607.                 being configured. Your application should get this value
  4608.                 by using the FTGetProcID routine, discussed    earlier in 
  4609.                 this chapter.
  4610.  
  4611.                 Note:     The refcon of the custom tool-settings dialog
  4612.                 box should point to a data structure (an example of 
  4613.                 which is shown next) in which the first two bytes are 
  4614.                 the tool procID and the next four bytes are magicCookie.
  4615.                 UserItem routines, for example, may require procID to 
  4616.                 obtain tool resources.    
  4617.  
  4618.                 TYPE
  4619.                     chooseDLOGdata=RECORD
  4620.                         procID:INTEGER
  4621.                         magicCookie:LONGINT
  4622.                 END;
  4623.  
  4624.  
  4625. æKY FTSetupSetup
  4626. æFa FileTransfers.a 
  4627. æFc FileTransfers.h 
  4628. æFp FileTransfers.p 
  4629. æMM 
  4630. æTN $A08B A0^.w=$212 (or #530)
  4631. æDT FTSetupSetup(procID: INTEGER; theConfig: Ptr; count: INTEGER; theDialog: DialogPtr; VAR magicCookie: LONGINT);
  4632. æC -----
  4633. Setting up tool-settings dialog box items
  4634.  
  4635. Procedure        FTSetupSetup(procID: INTEGER; theConfig: Ptr; count: 
  4636.                 INTEGER; theDialog: DialogPtr; VAR magicCookie: 
  4637.                 LONGINT);
  4638.  
  4639. Description:    FTSetupSetup tells the file transfer tool to set up 
  4640.                 controls (such as radio buttons or check boxes) in the
  4641.                 dialog item list returned by FTSetupPreflight.    
  4642.  
  4643.                 procID is the ID for the file transfer tool being 
  4644.                 configured. Your application should use the same value
  4645.                 for procID as it passed to FTSetupPreflight.         
  4646.  
  4647.                 theConfig is a pointer to a configuration record for the
  4648.                 tool being configured.    
  4649.  
  4650.                 count is the number of the first item in the dialog item
  4651.                 list appended to the dialog box.
  4652.  
  4653.                 theDialog is the dialog box in which configuration is 
  4654.                 taking place.    
  4655.  
  4656.                 magicCookie is a pointer to private storage for the file
  4657.                 transfer tool.    
  4658.  
  4659.  
  4660. æKY FTSetupFilter
  4661. æFa FileTransfers.a 
  4662. æFc FileTransfers.h 
  4663. æFp FileTransfers.p 
  4664. æMM 
  4665. æTN $A08B A0^.w=$213 (or #531)
  4666. æDT FTSetupFilter(procID: INTEGER; theConfig: Ptr; count: INTEGER; theDialog: DialogPtr; VAR theEvent: EventRecord; VAR theItem: INTEGER; VAR magicCookie: LONGINT): BOOLEAN;
  4667. æC -----
  4668. Filtering tool-settings dialog box events
  4669.  
  4670. Function        FTSetupFilter(procID: INTEGER; theConfig: Ptr; count:
  4671.                 INTEGER; theDialog: DialogPtr; VAR theEvent: 
  4672.                 EventRecord; VAR theItem: INTEGER; VAR magicCookie: 
  4673.                 LONGINT): BOOLEAN;
  4674.  
  4675. Description:    Your application calls FTSetupFilter as a filter 
  4676.                 procedure before it calls the standard modal dialog box 
  4677.                 filter procedure for the tool-settings dialog box. This
  4678.                 routine allows file transfer tools to filter events in 
  4679.                 the tool-settings dialog box.
  4680.  
  4681.                 procID is the ID for the file transfer tool that is 
  4682.                 being configured. Your application should use the same
  4683.                 value for procID as it passed to FTSetupPreflight.    
  4684.  
  4685.                 theConfig is the pointer to the configuration record for
  4686.                 the tool being configured.
  4687.  
  4688.                 count is the number of the first item in the dialog item
  4689.                 list appended to the dialog box.
  4690.  
  4691.                 theDialog is the dialog box performing the configuration.    
  4692.  
  4693.                 theEvent is the event record for which filtering is to 
  4694.                 take place.    
  4695.  
  4696.                 theItem can return the item clicked in the dialog box.    
  4697.  
  4698.                 magicCookie is a pointer to private storage for the file
  4699.                 transfer tool.    
  4700.                 
  4701.                 If the event passed in was handled, FTSetupFilter 
  4702.                 returns TRUE. FALSE indicates that your application 
  4703.                 should perform standard dialog box filtering.
  4704.  
  4705.  
  4706. æKY FTSetupItem
  4707. æFa FileTransfers.a 
  4708. æFc FileTransfers.h 
  4709. æFp FileTransfers.p 
  4710. æMM 
  4711. æTN $A08B A0^.w=$214 (or #532)
  4712. æDT FTSetupItem(procID: INTEGER; theConfig: Ptr; count: INTEGER; theDialog: DialogPtr; VAR theItem: INTEGER; VAR magicCookie: LONGINT);
  4713. æC -----
  4714. Processing tool-settings dialog box events
  4715.  
  4716. Procedure        FTSetupItem(procID: INTEGER; theConfig: Ptr; count: 
  4717.                 INTEGER; theDialog: DialogPtr; VAR theItem: INTEGER; 
  4718.                 VAR magicCookie: LONGINT);
  4719.  
  4720. Description:    FTSetupItem processes events for controls in the custom
  4721.                 tool-settings dialog box.
  4722.  
  4723.                 procID is the ID for the file transfer tool being 
  4724.                 configured. Your application should use the same value 
  4725.                 for procID as it passed to FTSetupPreflight.        
  4726.  
  4727.                 theConfig is a pointer to the configuration record for 
  4728.                 the tool being configured.
  4729.  
  4730.                 count is the number of the first item in the dialog item
  4731.                 list appended to the dialog box.
  4732.  
  4733.                 theDialog is the dialog box performing the configuration.    
  4734.  
  4735.                 theItem is the item clicked in the dialog box. This 
  4736.                 value can be modified and sent back.
  4737.  
  4738.                 magicCookie is a pointer to private storage for the file
  4739.                 transfer tool.    
  4740.  
  4741.  
  4742. æKY FTSetupCleanup
  4743. æFa FileTransfers.a 
  4744. æFc FileTransfers.h 
  4745. æFp FileTransfers.p 
  4746. æMM 
  4747. æTN $A08B A0^.w=$215 (or #533)
  4748. æDT FTSetupCleanup(procID: INTEGER; theConfig: Ptr; count: INTEGER; theDialog: DialogPtr; VAR magicCookie: LONGINT);
  4749. æC -----
  4750. Performing clean-up operations
  4751.  
  4752. Procedure        FTSetupCleanup(procID: INTEGER; theConfig: Ptr; count: 
  4753.                 INTEGER; theDialog: DialogPtr; VAR magicCookie: 
  4754.                 LONGINT);
  4755.  
  4756. Description:    FTSetupCleanup disposes of any storage allocated in 
  4757.                 FTSetupPreflight and performs other clean-up operations.
  4758.  
  4759.                 procID is the ID for the file transfer tool that is 
  4760.                 being configured. Your application should use the same 
  4761.                 value for procID as it passed to FTSetupPreflight.    
  4762.  
  4763.                 theConfig is the pointer to the configuration record for
  4764.                 the tool being configured.
  4765.  
  4766.                 count is the number of the first item in the dialog item
  4767.                 list appended to the dialog box.
  4768.  
  4769.                 theDialog is the dialog box performing the configuration.    
  4770.  
  4771.                 magicCookie is a pointer to private storage for the file
  4772.                 transfer tool.    
  4773.  
  4774.  
  4775. æKY FTSetupPostflight
  4776. æFa FileTransfers.a 
  4777. æFc FileTransfers.h 
  4778. æFp FileTransfers.p 
  4779. æMM 
  4780. æTN $A08B A0^.w=$21E (or #542)
  4781. æDT FTSetupPostflight(procID: INTEGER);
  4782. æC -----
  4783. Closing the tool file
  4784.  
  4785. Procedure        FTSetupPostflight(procID:INTEGER);
  4786.  
  4787. Description:    FTSetupPostflight closes the tool file if it is not 
  4788.                 being used by any session.    
  4789.  
  4790.                 procID is the ID for the file transfer tool that is 
  4791.                 being configured. Your application should use the same 
  4792.                 value for procID as it passed to FTSetupPreflight.    
  4793.                 
  4794.                 
  4795. æKY FTGetConfig
  4796. æFa FileTransfers.a 
  4797. æFc FileTransfers.h 
  4798. æFp FileTransfers.p 
  4799. æMM 
  4800. æTN $A08B A0^.w=$216 (or #534)
  4801. æDT FTGetConfig(hFT: FTHandle): Ptr;
  4802. æC -----
  4803. Getting the configuration string
  4804.  
  4805. Function        FTGetConfig(hFT: FTHandle): Ptr;
  4806.  
  4807. Description:    FTGetConfig gets a configuration string from the file 
  4808.                 transfer tool.    
  4809.  
  4810.                 FTGetConfig returns a null-terminated, C-style string 
  4811.                 from the file transfer tool containing tokens that fully
  4812.                 describe the configuration of the file transfer record. 
  4813.                 For an example, see the description of the next routine.
  4814.                 If an error occurs, FTGetConfig returns NIL.        
  4815.  
  4816.                 It is the responsibility of your application to dispose 
  4817.                 of Ptr.    
  4818.  
  4819.  
  4820. æKY FTSetConfig
  4821. æFa FileTransfers.a 
  4822. æFc FileTransfers.h 
  4823. æFp FileTransfers.p 
  4824. æMM 
  4825. æTN $A08B A0^.w=$217 (or #535)
  4826. æDT FTSetConfig(hFT: FTHandle; thePtr: Ptr): INTEGER;
  4827. æC -----
  4828. Setting the configuration string
  4829.  
  4830. Function        FTSetConfig(hFT: FTHandle; thePtr: Ptr): INTEGER;
  4831.  
  4832. Description:    FTSetConfig passes a configuration string to the file 
  4833.                 transfer tool.    
  4834.  
  4835.                 FTSetConfig passes a null-terminated, C-style string 
  4836.                 (see the example string    later in this section) to the 
  4837.                 file transfer tool for parsing. The string is pointed
  4838.                 to by thePtr and must contain tokens that describe the 
  4839.                 configuration of the file transfer record. The string 
  4840.                 can be any length. 
  4841.                     FTSetConfig ignores items it does not recognize or 
  4842.                 find relevant; such an    occurrence causes the file 
  4843.                 transfer tool to stop parsing the string and to return 
  4844.                 the character position where the error occurred. If the 
  4845.                 file transfer tool successfully parses the string, it 
  4846.                 returns ftNoErr. If the file transfer tool does    not 
  4847.                 successfully parse the string, it returns one of the 
  4848.                 following values: a number less than –1 to indicate an 
  4849.                 OSErr, –1 to indicate an unknown error, or a positive 
  4850.                 number to indicate the character position where parsing 
  4851.                 was stopped.
  4852.                     Individual file transfer tools are responsible for 
  4853.                 the parsing operation.
  4854.  
  4855. Sample:            A null-terminated, C-style configuration string    
  4856.  
  4857.                 InterCharDelay 0 InterLineDelay 0 WordWrap False Ending
  4858.                 CR\0
  4859.  
  4860.  
  4861. æKY FTStart
  4862. æFa FileTransfers.a 
  4863. æFc FileTransfers.h 
  4864. æFp FileTransfers.p 
  4865. æMM 
  4866. æTN $A08B A0^.w=$20B (or #523)
  4867. æDT FTStart(hFT: FTHandle; direction: FTDirection; fileInfo: SFReply): FTErr;
  4868. æC -----
  4869. Starting a file transfer
  4870.  
  4871. Function        FTStart(hFT: FTHandle; direction:FTDirection; 
  4872.                 fileInfo:SFReply): FTErr;
  4873.  
  4874. Description:    FTStart opens the file that is going to be involved in 
  4875.                 the file transfer, and initializes tool-private 
  4876.                 variables.
  4877.                     The value in the owner field in the file transfer 
  4878.                 record controls the    appearance of a status dialog box.
  4879.                     The code that performs the actual sending, receiving,
  4880.                 reading, and writing of data is the responsibility of 
  4881.                 your application. Your application specifies these 
  4882.                 routines when it creates the file transfer record. For a
  4883.                 description of the parameters that will be passed to 
  4884.                 these routines, see “Routines Your Application 
  4885.                 Provides,” later in this chapter.
  4886.  
  4887.                 direction describes the direction of the file transfer
  4888.                 and can be either ftReceiving, ftTransmitting, or 
  4889.                 ftFullDuplex.        
  4890.                     Once the file transfer has started, your application
  4891.                 needs to call FTExec every time it goes through its main
  4892.                 event loop. Calling FTExec gives the tool time to send 
  4893.                 and receive a packet of data, among other things.
  4894.  
  4895. Result Codes    ftGenericError, ftNoErr, ftRejected, ftFailed, 
  4896.                 ftTimeout, ftTooManyRetry, ftNotEnoughDspace, 
  4897.                 ftRemoteCancel, ftWrongFormat, ftUserCancel, 
  4898.                 ftNotSupported.
  4899.  
  4900.  
  4901. æKY FTExec
  4902. æFa FileTransfers.a 
  4903. æFc FileTransfers.h 
  4904. æFp FileTransfers.p 
  4905. æMM 
  4906. æTN $A08B A0^.w=$20A (or #522)
  4907. æDT FTExec(hFT: FTHandle);
  4908. æC -----
  4909. Processing file transfer data
  4910.  
  4911. Procedure        FTExec(hFT: FTHandle);
  4912.  
  4913. Description:    FTExec is the soul of the file transfer process because 
  4914.                 it allows the file transfer tool to implement the file 
  4915.                 transfer protocol. FTExec handles the disk input and 
  4916.                 output, either through your application or by performing
  4917.                 local disk input and output, if specified by your 
  4918.                 application. Every time your application calls FTExec, a
  4919.                 little piece of data is processed until there is no 
  4920.                 more data. 
  4921.                     When sending files, the file transfer tool reads 
  4922.                 data from your application with a readProc, and sends it
  4923.                 to the connection with a sendProc. When receiving files,
  4924.                 the file transfer tool gets data from your application 
  4925.                 with a recvProc, and checks if the data arrived 
  4926.                 correctly. The file transfer tool then writes the data 
  4927.                 with a writeProc.     
  4928.                     The readProc, sendProc, recvProc,and writeProc 
  4929.                 routines are discussed in “Routines Your Application 
  4930.                 Provides” later in this chapter.
  4931.                     At the end of the file transfer, the file transfer
  4932.                 tool is responsible for closing the file, releasing any 
  4933.                 memory allocated, and resetting the ftIsFTMode bit in 
  4934.                 the file transfer record.
  4935.  
  4936.  
  4937. æKY FTAbort
  4938. æFa FileTransfers.a 
  4939. æFc FileTransfers.h 
  4940. æFp FileTransfers.p 
  4941. æMM 
  4942. æTN $A08B A0^.w=$20D (or #525)
  4943. æDT FTAbort(hFT: FTHandle): FTErr;
  4944. æC -----
  4945. Stopping a file transfer
  4946.  
  4947. Function        FTAbort(hFT: FTHandle): FTErr;
  4948.  
  4949. Description:    FTAbort aborts a file transfer in progress. The file 
  4950.                 transfer tool sends the appropriate canceling characters
  4951.                 to the remote computer, and stops the file transfer.
  4952.  
  4953. Result Codes    ftGeneric, ftNoErr, ftRejected, ftFailed, ftNotSupported.
  4954.  
  4955.  
  4956. æKY FTDispose
  4957. æFa FileTransfers.a 
  4958. æFc FileTransfers.h 
  4959. æFp FileTransfers.p 
  4960. æMM 
  4961. æTN $A08B A0^.w=$209 (or #521)
  4962. æDT FTDispose(hFT: FTHandle);
  4963. æC -----
  4964. Disposing of a file transfer record
  4965.  
  4966. Procedure        FTDispose(hFT: FTHandle);
  4967.  
  4968. Description:    FTDispose disposes of the file transfer record and all 
  4969.                 associated data structures. The file transfer tool stops
  4970.                 any file transfer in progress (as specified by the file 
  4971.                 transfer record).
  4972.                 
  4973.                 
  4974. æKY FTActivate
  4975. æFa FileTransfers.a 
  4976. æFc FileTransfers.h 
  4977. æFp FileTransfers.p 
  4978. æMM 
  4979. æTN $A08B A0^.w=$220 (or #544)
  4980. æDT FTActivate(hFT: FTHandle; activate: BOOLEAN);
  4981. æC -----
  4982. Activate events
  4983.  
  4984. Procedure        FTActivate(hFT: FTHandle; activate: BOOLEAN);
  4985.  
  4986. Description:    FTActivate processes an activate or deactivate event 
  4987.                 (for instance, installing or removing a custom tool 
  4988.                 menu) for a window associated with the file transfer.
  4989.  
  4990.                 If activate is TRUE, the file transfer tool processes an
  4991.                 activate event.    Otherwise, it processes a deactivate 
  4992.                 event.
  4993.  
  4994.  
  4995. æKY FTResume
  4996. æFa FileTransfers.a 
  4997. æFc FileTransfers.h 
  4998. æFp FileTransfers.p 
  4999. æMM 
  5000. æTN $A08B A0^.w=$20E (or #526)
  5001. æDT FTResume(hFT: FTHandle; resume: BOOLEAN);
  5002. æC -----
  5003. Resume events
  5004.  
  5005. Procedure        FTResume(hFT: FTHandle; resume: BOOLEAN);
  5006.  
  5007. Description:    FTResume is called when your application receives a 
  5008.                 suspend or a resume event. The file transfer tool may 
  5009.                 decide to change timeout values or other parameters, 
  5010.                 depending on whether the application is running in the
  5011.                 foreground.
  5012.  
  5013.                 If resume is TRUE, the file transfer tool processes a 
  5014.                 resume event. Otherwise, it processes a suspend event.
  5015.  
  5016.  
  5017. æKY FTMenu
  5018. æFa FileTransfers.a 
  5019. æFc FileTransfers.h 
  5020. æFp FileTransfers.p 
  5021. æMM 
  5022. æTN $A08B A0^.w=$21F (or #543)
  5023. æDT FTMenu(hFT: FTHandle; menuID: INTEGER; item: INTEGER): BOOLEAN;
  5024. æC -----
  5025. Menu events
  5026.  
  5027. Function        FTMenu(hFT: FTHandle; menuID: INTEGER; item: INTEGER): 
  5028.                 BOOLEAN;
  5029.  
  5030. Description:    Your application must call FTMenu when the user chooses 
  5031.                 an item from a menu installed by the file transfer tool.
  5032.  
  5033.                 FTMenu returns FALSE if the file transfer tool did not 
  5034.                 handle the menu event.        
  5035.  
  5036.                 FTMenu returns TRUE if the file transfer tool did handle
  5037.                 the menu event.        
  5038.  
  5039.  
  5040. æKY FTEvent
  5041. æFa FileTransfers.a 
  5042. æFc FileTransfers.h 
  5043. æFp FileTransfers.p 
  5044. æMM 
  5045. æTN $A08B A0^.w=$21D (or #541)
  5046. æDT FTEvent(hFT: FTHandle; theEvent: EventRecord);
  5047. æC -----
  5048. Other events
  5049.  
  5050. Procedure        FTEvent(hFT: FTHandle; theEvent: EventRecord);
  5051.  
  5052. Description:    When your application receives an event, it should check
  5053.                 if the refcon of the window is a tool’s hFT. Such an 
  5054.                 event occurs, for example, when the user clicks a button
  5055.                 in a dialog box displayed by the file transfer tool. If
  5056.                 it does belong to a file transfer tool’s window, your
  5057.                 application can call FTEvent.    
  5058.  
  5059.                 A window (or dialog box) created by a file transfer tool
  5060.                 has a file transfer record handle stored in the refCon 
  5061.                 field for windowRecord.         
  5062.  
  5063.  
  5064. æKY FTIntlToEnglish
  5065. æFa FileTransfers.a 
  5066. æFc FileTransfers.h 
  5067. æFp FileTransfers.p 
  5068. æMM 
  5069. æTN $A08B A0^.w=$218 (or #536)
  5070. æDT FTIntlToEnglish(hFT: FTHandle; inputPtr: Ptr; VAR outputPtr: Ptr; language: INTEGER): OSErr;
  5071. æC -----
  5072. Translating into English
  5073.  
  5074. Function        FTIntlToEnglish(hFT: FTHandle; inputPtr: Ptr; VAR 
  5075.                 outputPtr: Ptr; language: INTEGER): OSErr;
  5076.  
  5077. Description:    FTIntlToEnglish converts a configuration string, which 
  5078.                 is pointed to by inputPtr, to an American English 
  5079.                 configuration string pointed to by outputPtr.    
  5080.  
  5081.                 This function returns an operating system error code if 
  5082.                 any internal errors    occur.
  5083.                     The file transfer tool allocates space for outputPtr.
  5084.                 Your application is    responsible for disposing of the 
  5085.                 pointer with DisposPtr when done with it.    
  5086.                     language specifies the language from which the 
  5087.                 string is to be converted. Valid values for this field 
  5088.                 are shown in the description of the Script Manager in 
  5089.                 Inside Macintosh, Volume V.     If the language specified 
  5090.                 is not supported, this routine returns noErr, but 
  5091.                 outputPtr is NIL.            
  5092.  
  5093.  
  5094. æKY FTEnglishToIntl
  5095. æFa FileTransfers.a 
  5096. æFc FileTransfers.h 
  5097. æFp FileTransfers.p 
  5098. æMM 
  5099. æTN $A08B A0^.w=$219 (or #537)
  5100. æDT FTEnglishToIntl(hFT: FTHandle; inputPtr: Ptr; VAR outputPtr: Ptr; language: INTEGER): OSErr;
  5101. æC -----
  5102. Translating from English
  5103.  
  5104. Function        FTEnglishToIntl(hFT: FTHandle; inputPtr: Ptr; VAR 
  5105.                 outputPtr: Ptr; language: INTEGER): OSErr;
  5106.  
  5107. Description:    FTEnglishToIntl converts an American English 
  5108.                 configuration string, which is pointed to by inputPtr, 
  5109.                 to a configuration string pointed to by outputPtr.            
  5110.  
  5111.                 This function returns an operating system error code if
  5112.                 any internal errors    occur.
  5113.                     The file transfer tool allocates space for 
  5114.                 outputPtr; your application is responsible for disposing
  5115.                 of the pointer with DisposPtr when done with it.    
  5116.                     language specifies the language to which the string
  5117.                 is to be converted.    Valid values for this field are 
  5118.                 shown in the description of the Script Manager in Inside
  5119.                 Macintosh, Volume V. If the language specified is not 
  5120.                 supported, noErr is    still returned, but outputPtr is NIL.        
  5121.  
  5122.  
  5123. æKY FTGetToolName
  5124. æFa FileTransfers.a 
  5125. æFc FileTransfers.h 
  5126. æFp FileTransfers.p 
  5127. æMM 
  5128. æTN $A08B A0^.w=$206 (or #518)
  5129. æDT FTGetToolName(procID: INTEGER; VAR name: Str255);
  5130. æC -----
  5131. Getting the name of a tool
  5132.  
  5133. Procedure        FTGetToolName(procID: INTEGER; VAR name: Str255);
  5134.  
  5135. Description:     FTGetToolName returns in name the name of the tool 
  5136.                 specified by procID.        
  5137.  
  5138.                 If procID references a file transfer tool that does not
  5139.                 exist, the File Transfer Manager sets name to an empty 
  5140.                 string.    
  5141.  
  5142. æKY FTSetRefCon
  5143. æFa FileTransfers.a 
  5144. æFc FileTransfers.h 
  5145. æFp FileTransfers.p 
  5146. æMM 
  5147. æTN $A08B A0^.w=$202 (or #514)
  5148. æDT FTSetRefCon(hFT: FTHandle; refCon: LONGINT); 
  5149. æC -----
  5150. Setting the file transfer record's reference constant
  5151.  
  5152. Procedure        FTSetRefCon(hFT: FTHandle; refCon: LONGINT); 
  5153.  
  5154. Description:    FTSetRefCon sets the file transfer record refCon to the 
  5155.                 given value. It is very important that your application 
  5156.                 use this routine to change the value of the reference 
  5157.                 constant, instead of changing it directly.
  5158.  
  5159.  
  5160. æKY FTGetRefCon
  5161. æFa FileTransfers.a 
  5162. æFc FileTransfers.h 
  5163. æFp FileTransfers.p 
  5164. æMM 
  5165. æTN $A08B A0^.w=$203 (or #515)
  5166. æDT FTGetRefCon(hFT: FTHandle): LONGINT;
  5167. æC -----
  5168. Getting the file transfer record reference constant
  5169.  
  5170. Function        FTGetRefCon(hFT: FTHandle): LONGINT;
  5171.  
  5172. Description:    FTGetRefCon returns the file transfer record reference 
  5173.                 constant.    
  5174.  
  5175.  
  5176. æKY FTSetUserData
  5177. æFa FileTransfers.a 
  5178. æFc FileTransfers.h 
  5179. æFp FileTransfers.p 
  5180. æMM 
  5181. æTN $A08B A0^.w=$204 (or #516)
  5182. æDT FTSetUserData(hFT: FTHandle; userData: LONGINT);
  5183. æC -----
  5184. Setting the userData field
  5185.  
  5186. Procedure        FTSetUserData(hFT: FTHandle; userData: LONGINT);
  5187.  
  5188. Description:    FTSetUserData sets the file transfer record’s userData 
  5189.                 field to the given value. It is very important that your
  5190.                 application use this routine to change the value of the
  5191.                 userData field, instead of changing it directly.
  5192.  
  5193.  
  5194. æKY FTGetUserData 
  5195. æFa FileTransfers.a 
  5196. æFc FileTransfers.h 
  5197. æFp FileTransfers.p 
  5198. æMM 
  5199. æTN $A08B A0^.w=$205 (or #517)
  5200. æDT FTGetUserData(hFT: FTHandle): LONGINT;
  5201. æC -----
  5202. Getting the userData field
  5203.  
  5204. Function        FTGetUserData(hFT: FTHandle) : LONGINT;
  5205.  
  5206. Description:    FTGetUserData returns the file transfer record’s 
  5207.                 userData field.        
  5208.  
  5209.  
  5210. æKY FTGetVersion
  5211. æFa FileTransfers.a 
  5212. æFc FileTransfers.h 
  5213. æFp FileTransfers.p 
  5214. æMM 
  5215. æTN $A08B A0^.w=$21A (or #538)
  5216. æDT FTGetVersion(hFT: FTHandle): Handle;
  5217. æC -----
  5218. Getting 'vers' resource information
  5219.  
  5220. Function        FTGetVersion(hFT: FTHandle): Handle;
  5221.  
  5222. Description:    FTGetVersion returns a handle to a relocatable block 
  5223.                 that contains the information in the file transfer 
  5224.                 tool’s 'vers' resource with ID=1. Your application is 
  5225.                 responsible for disposing of the handle when done with 
  5226.                 it.
  5227.                 
  5228.                 Note:     The handle returned is not a resource handle.    
  5229.  
  5230.  
  5231. æKY FTGetFTVersion
  5232. æFa FileTransfers.a 
  5233. æFc FileTransfers.h 
  5234. æFp FileTransfers.p 
  5235. æMM 
  5236. æTN $A08B A0^.w=$21B (or #539)
  5237. æDT FTGetFTVersion: INTEGER;
  5238. æC -----
  5239. Getting the File Transfer Manager version number
  5240.  
  5241. Function        FTGetFTVersion: INTEGER;
  5242.  
  5243. Description:    FTGetFTVersion returns the version number of the File
  5244.                 Transfer Manager.    
  5245.  
  5246.                 The version number of the File Transfer Manager 
  5247.                 described in this document is:    
  5248.  
  5249.                 CONST
  5250.                     curFTVersion    =    1;
  5251.                     
  5252.                     
  5253. æKY MyReadProc
  5254. æDT MyReadProc(VAR count: LONGINT; bufPtr: Ptr; refCon: LONGINT; fileMsg: INTEGER): OSErr;
  5255. æC -----
  5256. Reading data
  5257.  
  5258. Function        MyReadProc(VAR count : LONGINT; bufPtr : Ptr; refCon :
  5259.                 LONGINT; fileMsg : INTEGER) : OSErr;
  5260.  
  5261. Description:    MyReadProc is a routine in your application that the 
  5262.                 file transfer tool calls to read data from a file. After
  5263.                 MyReadProc reads the data, the file transfer tool 
  5264.                 typically sends the data by calling the MySendProc 
  5265.                 routine, which is described next. MyReadProc is also 
  5266.                 responsible for opening and closing the file from which 
  5267.                 the outgoing data is read.
  5268.  
  5269.                 MyReadProc must return an error code when appropriate.
  5270.                 
  5271.                 count is a bit field with the following bit masks 
  5272.                 defined:    
  5273.  
  5274.                 CONST
  5275.                     ftOpenDataFork        =        $00000001;
  5276.                     ftOpenRsrcFork        =        $00000002;
  5277.  
  5278.                 refCon is the reference constant of the file transfer 
  5279.                 record.    
  5280.  
  5281.                 fileMsg specifies which service the file transfer tool
  5282.                 requires MyReadProc to provide.
  5283.  
  5284.                 CONST    
  5285.                     ftReadOpenFile        =        0;
  5286.                     ftReadDataFork        =        1;
  5287.                     ftReadRsrcFork        =        2;
  5288.                     ftReadAbort            =        3;
  5289.                     ftReadComplete        =        4;
  5290.                     
  5291.                 ftReadOpenFile
  5292.                 ftReadOpenFile indicates that the file transfer tool 
  5293.                 requires MyReadProc to open a file. The bits set in 
  5294.                 count specify whether MyReadProc should open the        
  5295.                 resource fork, data fork, or both. bufPtr points to a 
  5296.                 parameter block that specifies the file MyReadProc 
  5297.                 should open. The parameter block the file transfer tool
  5298.                 passes to MyReadProc is the same as that returned from
  5299.                 calling PBGetFInfo.    
  5300.  
  5301.                 ftReadDataFork and ftReadRsrcFork         
  5302.                 These messages indicate that the file transfer tool 
  5303.                 requires MyReadProc to read data from an open file, 
  5304.                 which it had previously opened in response to 
  5305.                 ftReadOpenFile. count specifies the number of bytes 
  5306.                 MyReadProc should read. When finished reading, 
  5307.                 MyReadProc puts the actual number of bytes read into    
  5308.                 count.    bufPtr points to the buffer into which 
  5309.                 MyReadProc should read data.             
  5310.  
  5311.                 ftReadAbort and ftReadComplete              
  5312.                 These messages indicate that MyReadProc should close the
  5313.                 file it had opened in response to ftReadOpenFile.     
  5314.  
  5315.  
  5316. æKY MySendProc
  5317. æC -----
  5318. Sending data
  5319.  
  5320. Function        MySendProc(thePtr: Ptr; theSize: LONGINT; refCon: 
  5321.                 LONGINT; channel: CMChannel; flags: CMFlags):LONGINT;
  5322.  
  5323. Description:    MySendProc is a routine in your application that the 
  5324.                 file transfer tool calls to send data that is in a 
  5325.                 buffer.
  5326.  
  5327.                 MySendProc must return the actual number of bytes it 
  5328.                 sent.    
  5329.  
  5330.                 thePtr is a pointer to a block of data in memory that is
  5331.                 to be sent.    
  5332.  
  5333.                 theSize is the length of that block.    
  5334.  
  5335.                 refCon is the reference constant of the file transfer 
  5336.                 record.    
  5337.                 
  5338.                 channel specifies the channel that the file transfer 
  5339.                 tool can use. Your application should specify one of the
  5340.                 following values for channel: CMData, CMCntl, or CMAttn.        
  5341.                 
  5342.                 flags is described in Chapter 3 under the description of
  5343.                 CMWrite.         
  5344.  
  5345. Sample send routine
  5346.  
  5347. FUNCTION MySendProc(thePtr: Ptr;theSize: LONGINT;refcon: LONGINT;
  5348.                     channel: CMChannel;flags: INTEGER) : LONGINT;
  5349. VAR
  5350.         theErr : CMErr;                        { Errors on a write }
  5351.  
  5352. BEGIN
  5353.         MySendProc:= 0;                        { Assume the worst }
  5354.  
  5355.         IF gConn <> NIL THEN BEGIN            { Send the data }
  5356.                 theErr := CMWrite(gConn,thePtr,theSize,channel,FALSE, 
  5357.                     NIL, 0, flags);
  5358.                 IF (theErr = noErr) THEN
  5359.                     MySendProc:= theSize    { if ok, we sent all }
  5360.                 ELSE
  5361.                     ;                        { Handle errors }
  5362.                 END; { Good Connection    }
  5363. END; { MySendProc }
  5364.  
  5365.  
  5366. æKY MyRecvProc
  5367. æC -----
  5368. Receiving data
  5369.  
  5370. Function        MyRecvProc (thePtr: Ptr; theSize: LONGINT; refCon:
  5371.                 LONGINT; channel: CMChannel; VAR flags: CMFlags):
  5372.                 LONGINT;
  5373.  
  5374. Description:    MyRecvProc is a routine in your application that the 
  5375.                 file transfer tool uses to receive data into a buffer 
  5376.                 from the connection.
  5377.  
  5378.                 MyRecvProc must return the actual number of bytes it 
  5379.                 received.    
  5380.  
  5381.                 thePtr is a pointer to a block of data in memory where 
  5382.                 the incoming data is to    be placed.
  5383.  
  5384.                 theSize is the length of that data.    
  5385.  
  5386.                 refCon is the reference constant of the file transfer 
  5387.                 record.    
  5388.  
  5389.                 channel specifies the data channel that the file 
  5390.                 transfer tool can use. Your    application should specify 
  5391.                 one of the following values for channel: CMData, CMCntl,
  5392.                 or CMAttn.         
  5393.  
  5394.                 flags is described in Chapter 3 under the description of
  5395.                 CMRead.        
  5396.  
  5397. Sample receive routine
  5398.  
  5399. FUNCTION MyRecvProc (thePtr: Ptr;theSize: LONGINT;refcon: LONGINT;
  5400.                      channel: CMChannel;VAR flags: INTEGER): LONGINT;
  5401. VAR
  5402.         theErr : CMErr;                        { Any errors }
  5403.  
  5404. BEGIN        
  5405.         MyRecvProc := 0;                    { Assume the worst }
  5406.  
  5407.         IF gConn <> NIL THEN BEGIN
  5408.                                             { Read all the data }
  5409.             theErr := CMRead(gConn,thePtr,theSize,channel,FALSE,NIL,0,
  5410.                     flags);
  5411.             IF (theErr <> noErr) THEN
  5412.                     MyRecvProc := theSize    { if ok, we got all }
  5413.             ELSE
  5414.                     ;                        { Handle errors }
  5415.         END; { Good Connection }
  5416. END; { MyRecvProc }
  5417.  
  5418.  
  5419. æKY MyWriteProc
  5420. æC -----
  5421. Writing data
  5422.  
  5423. Function        MyWriteProc(VAR count: LONGINT; bufPtr: Ptr; refCon: 
  5424.                 LONGINT; fileMsg: INTEGER): OSErr;
  5425.  
  5426. Description:    MyWriteProc is a routine in your application that the 
  5427.                 file transfer tool calls to write data to a file.    
  5428.                 MyWriteProc is also responsible for opening and closing 
  5429.                 the file to which the outgoing data is written.
  5430.  
  5431.                 MyWriteProc must return an error code when appropriate.    
  5432.  
  5433.                 count is a bit field with the following bit masks 
  5434.                 defined:    
  5435.  
  5436.                 CONST
  5437.                     ftOpenDataFork        =        1;
  5438.                     ftOpenRsrcFork        =        2;
  5439.  
  5440.                 refCon is the reference constant of the file transfer
  5441.                 record.    
  5442.  
  5443.                 fileMsg specifies which service the file transfer tool 
  5444.                 requires MyWriteProc to provide.
  5445.  
  5446.                 CONST    
  5447.                     ftWriteOpenFile        =        0;
  5448.                     ftWriteDataFork        =        1;
  5449.                     ftWriteRsrcFork        =        2;
  5450.                     ftWriteAbort        =        3;
  5451.                     ftWriteComplete        =        4;
  5452.                     ftWriteFileInfo        =        5;
  5453.                     
  5454.                 ftWriteOpenFile                    
  5455.                 ftWriteOpenFile indicates that the file transfer 
  5456.                 tool requires MyWriteProc to open a file. The bits 
  5457.                 set in count specify whether MyWriteProc should open        
  5458.                 the resource fork, data fork, or both. bufPtr points
  5459.                 to a parameter block that specifies the file 
  5460.                 MyWriteProc should open. The parameter block the 
  5461.                 file transfer tool passes to MyWriteProc is the same
  5462.                 as that returned from calling PBGetFInfo.    
  5463.                     
  5464.                     Note that MyWriteProc creates the file specified by
  5465.                     the parameter block. If the    file transfer protocol 
  5466.                     in use does not specify the filename for the 
  5467.                     incoming file, MyWriteProc must generate one. Your 
  5468.                     application must handle filename conflicts and 
  5469.                     AppleShare file server permission problems if they 
  5470.                     arise.
  5471.  
  5472.                 ftWriteDataFork    and ftWriteRsrcFork         
  5473.                 These messages indicate that the file transfer tool
  5474.                 requires MyWriteProc to    open a file. count specifies
  5475.                 the number of bytes to write. When finished    writing 
  5476.                 data, MyWriteProc should set count to the actual 
  5477.                 number of bytes    written. bufPtr points to the buffer
  5478.                 into which MyWriteProc should write data.             
  5479.  
  5480.                 ftWriteAbort
  5481.                 ftWriteAbort indicates that MyWriteProc should close the
  5482.                 open file and delete it.
  5483.  
  5484.                 ftWriteComplete
  5485.                 ftWriteComplete indicates that MyWriteProc should close
  5486.                 the open file.        
  5487.  
  5488.                 ftWriteFileInfo
  5489.                 ftWriteFileInfo indicates that the file transfer tool 
  5490.                 requires MyWriteProc to    change file information. bufPtr
  5491.                 points to a parameter block that MyWriteProc can pass to
  5492.                 the File Manager routine PBSetFInfo.        
  5493.  
  5494.  
  5495. æKY MyEnvironsProc
  5496. æC -----
  5497. Getting the connection environment
  5498.  
  5499. Function        MyEnvironsProc(refCon: LONGINT; VAR theEnvirons:
  5500.                 ConnEnvironRec): CMErr;
  5501.  
  5502. Description:    Sometimes the file transfer tool needs to know about the
  5503.                 type of connection on which to transfer files. For 
  5504.                 example, some file transfer protocols require an 8-bit 
  5505.                 data channel. To get this information, the file transfer
  5506.                 tool calls a routine in your application, MyEnvironsProc.    
  5507.  
  5508.                 refCon is the reference constant of the file transfer 
  5509.                 record.    
  5510.  
  5511.                 theEnvirons is a data structure containing the 
  5512.                 connection-environment record. Your application can 
  5513.                 either construct theEnvirons or use the Connection 
  5514.                 Manager routine CMGetConnEnvirons. For more information
  5515.                 about theEnvirons, see “CMGetConnEnvirons Getting the 
  5516.                 Connection Environment” in Chapter 3.
  5517.                     The example that follows shows how MyEnvironsProc 
  5518.                 can point to a Connection Manager routine to retrieve 
  5519.                 information about the connection environment.
  5520.  
  5521. Result Codes    cmGenericError, cmNoErr, cmNotSupported, envVersTooBig.
  5522.  
  5523.  
  5524. Sample connection-environment routine
  5525. FUNCTION MyEnvironsProc(refCon: LONGINT; VAR theEnvirons: 
  5526.             ConnEnvironRec): OSErr;
  5527. BEGIN
  5528.         MyEnvironsProc:= envNotPresent;            { pessimism }
  5529.         
  5530.         { Get the connection info }
  5531.         IF gConn <> NIL THEN                    { Tool sets the version }
  5532.                 MyEnvironsProc:= CMGetConnEnvirons(gConn,theEnvirons);
  5533. END; { MyEnvironsProc}
  5534.  
  5535.  
  5536. æKY Communication Toolbox
  5537. æC -----
  5538. Connection Manager
  5539. File Transfer Manager
  5540. Terminal Manager
  5541. Communications Resource Manager
  5542.  
  5543. æKY CTB
  5544. æC -----
  5545. Connection Manager
  5546. File Transfer Manager
  5547. Terminal Manager
  5548. Communications Resource Manager
  5549.  
  5550.  
  5551.  
  5552. æKY Communications Resource Manager
  5553. æC -----
  5554. CRMGet1IndResource                CRMGetResource
  5555. CRMGet1NamedResource            CRMInstall
  5556. CRMGet1Resource                    CRMLocalToRealID
  5557. CRMGetCRMVersion                CRMRealToLocalID
  5558. CRMGetHeader                    CRMReleaseResource
  5559. CRMGetIndex                        CRMRemove
  5560. CRMGetIndResource                CRMSearch
  5561. CRMGetIndToolName                InitCRM
  5562. CRMGetNamedResource                
  5563.  
  5564. CRMRecord
  5565.  
  5566.  
  5567. æKY CommResources
  5568. æC -----
  5569. CRMGet1IndResource                CRMGetResource
  5570. CRMGet1NamedResource            CRMInstall
  5571. CRMGet1Resource                    CRMLocalToRealID
  5572. CRMGetCRMVersion                CRMRealToLocalID
  5573. CRMGetHeader                    CRMReleaseResource
  5574. CRMGetIndex                        CRMRemove
  5575. CRMGetIndResource                CRMSearch
  5576. CRMGetIndToolName                InitCRM
  5577. CRMGetNamedResource                
  5578.  
  5579. CRMRecord
  5580.  
  5581.  
  5582. æKY CRMgr
  5583. æC -----
  5584. CRMGet1IndResource                CRMGetResource
  5585. CRMGet1NamedResource            CRMInstall
  5586. CRMGet1Resource                    CRMLocalToRealID
  5587. CRMGetCRMVersion                CRMRealToLocalID
  5588. CRMGetHeader                    CRMReleaseResource
  5589. CRMGetIndex                        CRMRemove
  5590. CRMGetIndResource                CRMSearch
  5591. CRMGetIndToolName                InitCRM
  5592. CRMGetNamedResource                
  5593.  
  5594. CRMRecord
  5595.  
  5596.  
  5597. æKY CRMRecord
  5598. æC -----
  5599. TYPE
  5600.     CRMRecPtr             =        ^CRMRec;
  5601.     CRMRec                 =        RECORD
  5602.         qLink                :        QElemPtr;
  5603.         qType                :        INTEGER;
  5604.         crmVersion            :        INTEGER;
  5605.         crmPrivate            :        LONGINT; 
  5606.         crmReserved            :        INTEGER;
  5607.         crmDeviceType        :        LONGINT;
  5608.         crmDeviceID            :        LONGINT;
  5609.         crmAttributes        :        LONGINT;
  5610.         crmStatus            :        LONGINT;
  5611.         crmRefCon            :        LONGINT;
  5612.     END;
  5613.  
  5614.  
  5615. qLink
  5616. qLink points to the next CRMRec in the Communications Resource Manager’s 
  5617. queue of communications resource records.
  5618.  
  5619.  
  5620. qType
  5621. qType is a constant that your code must fill with the constant crmType.         
  5622.  
  5623.  
  5624. crmVersion
  5625. crmVersion is the version number of the CRMRec data structure. At this 
  5626. time there is only one version, so the Communications Resource Manager 
  5627. fills this with the constant crmRecVersion.    
  5628.  
  5629.  
  5630. crmPrivate and crmReserved
  5631. crmPrivate and crmReserved are private to the Communications Resource 
  5632. Manager; your code must not use them.
  5633.  
  5634.  
  5635. crmDeviceType
  5636. crmDeviceType is the type of device. For example, a serial port has a    
  5637. crmDeviceType of crmSerialDevice.    
  5638.  
  5639.  
  5640. crmDeviceID
  5641. crmDeviceID is an identifier that your code can use to distinguish 
  5642. between multiple devices of the same device type. The Communications 
  5643. Resource Manager fills in this field when your code calls the 
  5644. CRMInstall routine.    
  5645.  
  5646.  
  5647. crmAttributes
  5648. crmAttributes specifies the attributes of a specific device type. This 
  5649. field can hold either a pointer to the data or the actual data that 
  5650. describes the device. A sample crmAttributes data structure appears later
  5651. in this chapter in the section “Registering a Device.”
  5652.  
  5653.  
  5654. crmStatus
  5655. crmStatus specifies the status of a device. Your code can use this field 
  5656. for device arbitration purposes.
  5657.  
  5658.  
  5659. crmRefCon
  5660. crmRefCon is not used in this release of the Communications Resource 
  5661. Manager.    
  5662.  
  5663.  
  5664. æKY InitCRM
  5665. æFa CommResources.a
  5666. æFc CommResources.h
  5667. æFp CommResources.p
  5668. æMM
  5669. æTN $A08B A0^.w=$501 (or #1281)
  5670. æDT InitCRM:    CRMErr;
  5671. æC -----
  5672. Initializing the Communications Resource Manager
  5673.  
  5674. Function        InitCRM:CRMErr;
  5675.  
  5676. Description:    InitCRM initializes the Communications Resource Manager.    
  5677.  
  5678.                 Warning:    Your code must call this routine after 
  5679.                 calling the standard Macintosh Toolbox initialization
  5680.                 routines and before calling any of the other 
  5681.                 Communications Toolbox manager initialization routines.      
  5682.  
  5683.                 InitCRM returns an operating system error code if 
  5684.                 appropriate. 
  5685.                     Your code must check for the presence of the 
  5686.                 Communications Toolbox before calling this function.
  5687.                 Sample code under “Determining Whether the Managers Are 
  5688.                 Installed” in Appendix C shows you how your application 
  5689.                 can make this check.
  5690.  
  5691. Result Codes    crmGenericError, crmNoErr.
  5692.  
  5693.  
  5694. æKY CRMInstall
  5695. æFa CommResources.a
  5696. æFc CommResources.h
  5697. æFp CommResources.p
  5698. æMM
  5699. æTN $A08B A0^.w=$503 (or #1283)
  5700. æDT CRMInstall(crmReqPtr: QElemPtr);
  5701. æC -----
  5702. Installing devices
  5703.  
  5704. Procedure        CRMInstall(crmReqPtr: QElemPtr);
  5705.  
  5706. Description:    CRMInstall installs a device into the Communications 
  5707.                 Resource Manager’s queue. Devices in the Communications 
  5708.                 Resource Manager queue typically have their CRMRec 
  5709.                 records allocated in the system heap. If your code 
  5710.                 installs a CRMRec at startup time, be sure that your code
  5711.                 increases the size of the system heap appropriately.
  5712.                     For more information on how to register a device with
  5713.                 the Communications Resource Manager, read “Registering a
  5714.                 Device,” later in this chapter.
  5715.  
  5716.                 CRMInstall installs the communications resource record 
  5717.                 crmReqPtr into the Communications Resource Manager queue.
  5718.  
  5719.                 Warning:    A CRMRec allocated in the application heap
  5720.                 needs to be removed before the application heap is 
  5721.                 reinitialized; otherwise, the Communications Resource 
  5722.                 Manager queue may be damaged.      
  5723.  
  5724.  
  5725. æKY CRMSearch
  5726. æFa CommResources.a
  5727. æFc CommResources.h
  5728. æFp CommResources.p
  5729. æMM
  5730. æTN $A08B A0^.w=$505 (or #1285)
  5731. æDT CRMSearch(crmReqPtr: QElemPtr): QElemPtr;
  5732. æC -----
  5733. Searching for devices
  5734.  
  5735. Function        CRMSearch(crmReqPtr: QElemPtr): QElemPtr;
  5736.  
  5737. Description:    Your code can use CRMSearch to order the Communications 
  5738.                 Resource Manager queue, or to add new elements to the end
  5739.                 of the queue.
  5740.  
  5741.                 crmReqPtr specifies communications resource record search
  5742.                 criteria.    
  5743.                     CRMSearch searches for a device in the Communications
  5744.                 Resource Manager queue that has two characteristics: the
  5745.                 same deviceType, and a deviceID greater than the deviceID
  5746.                 in the record specified by crmReqPtr. CRMSearch returns a
  5747.                 pointer to the first record that it finds that meets 
  5748.                 these two conditions. Or, if no records meet the search 
  5749.                 criteria, it returns NIL.    
  5750.                     When searching for the first element in the queue, 
  5751.                 your code must pass 0 in deviceID.    
  5752.  
  5753.  
  5754. æKY CRMRemove
  5755. æFa CommResources.a
  5756. æFc CommResources.h
  5757. æFp CommResources.p
  5758. æMM
  5759. æTN $A08B A0^.w=$504 (or #1284)
  5760. æDT CRMRemove(crmReqPtr: QElemPtr): OSErr;
  5761. æC -----
  5762. Removing devices
  5763.  
  5764. Function        CRMRemove(crmReqPtr: QElemPtr): OSErr;
  5765.  
  5766. Description:    CRMRemove removes a device from the Communications 
  5767.                 Resource Manager queue.
  5768.  
  5769.                 crmReqPtr specifies the device to be removed.        
  5770.  
  5771.  
  5772. æKY CRMGetCRMVersion
  5773. æFa CommResources.a
  5774. æFc CommResources.h
  5775. æFp CommResources.p
  5776. æMM
  5777. æTN $A08B A0^.w=$506 (or #1286)
  5778. æDT CRMGetCRMVersion: INTEGER;
  5779. æC -----
  5780. Getting the version number
  5781.  
  5782. Function        CRMGetCRMVersion: INTEGER;
  5783.  
  5784. Description:    CRMGetCRMVersion returns the version number of the 
  5785.                 Communications Resource    Manager.
  5786.  
  5787.                 The Communications Resource Manager version described in 
  5788.                 this document is:    
  5789.  
  5790.                 CONST
  5791.                     curCRMVersion        =        1;
  5792.  
  5793.  
  5794. æKY CRMGetHeader
  5795. æFa CommResources.a
  5796. æFc CommResources.h
  5797. æFp CommResources.p
  5798. æMM
  5799. æTN $A08B A0^.w=$502 (or #1282)
  5800. æDT CRMGetHeader: QHdrPtr;
  5801. æC -----
  5802. Getting to the head of the queue
  5803.  
  5804. Function        CRMGetHeader: QHdrPtr;
  5805.  
  5806. CRMGetHeader returns a pointer to the head of the Communications Resource    
  5807. Manager queue.
  5808.  
  5809.  
  5810. æKY CRMGetResource
  5811. æFa CommResources.a
  5812. æFc CommResources.h
  5813. æFp CommResources.p
  5814. æMM
  5815. æTN $A08B A0^.w=$507 (or #1287)
  5816. æDT CRMGetResource(theType: ResType; theID: INTEGER): Handle;
  5817. æC -----
  5818. Loading resources
  5819.  
  5820. Function        CRMGetResource(theType: ResType; theID: INTEGER): Handle;
  5821.  
  5822.                 CRMGetResource and CRMGet1Resource call the Resource 
  5823.                 Manager routines GetResource and Get1Resource, 
  5824.                 respectively, and return a handle to the specified 
  5825.                 communications resource. The Communications Resource 
  5826.                 Manager then adds the handle to the list of resources 
  5827.                 that it is managing, and increases by one the use count,
  5828.                 which indicates how many pieces of code are using a 
  5829.                 resource.
  5830.  
  5831.  
  5832. æKY CRMGet1Resource
  5833. æFa CommResources.a
  5834. æFc CommResources.h
  5835. æFp CommResources.p
  5836. æMM
  5837. æTN $A08B A0^.w=$508 (or #1288)
  5838. æDT CRMGet1Resource(theType: ResType; theID: INTEGER): Handle;
  5839. æC -----
  5840. Loading resources
  5841.  
  5842. Function        CRMGet1Resource(theType: ResType; theID: INTEGER): Handle;
  5843.  
  5844.                 CRMGetResource and CRMGet1Resource call the Resource 
  5845.                 Manager routines GetResource and Get1Resource, 
  5846.                 respectively, and return a handle to the specified 
  5847.                 communications resource. The Communications Resource 
  5848.                 Manager then adds the handle to the list of resources 
  5849.                 that it is managing, and increases by one the use count,
  5850.                 which indicates how many pieces of code are using a 
  5851.                 resource.
  5852.  
  5853.  
  5854. æKY CRMGetIndResource
  5855. æFa CommResources.a
  5856. æFc CommResources.h
  5857. æFp CommResources.p
  5858. æMM
  5859. æTN $A08B A0^.w=$509 (or #1289)
  5860. æDT CRMGetIndResource(theType: ResType; index: INTEGER): Handle;
  5861. æC -----
  5862. Loading indexed resources
  5863.  
  5864. Function        CRMGetIndResource(theType: ResType; index: INTEGER): Handle;
  5865.  
  5866.                 CRMGetIndResource and CRMGet1IndResource call the 
  5867.                 Resource Manager routines GetIndResource and 
  5868.                 Get1IndResource, respectively, and return a handle to the
  5869.                 specified communications resource. The Communications 
  5870.                 Resource Manager then adds the handle to the list of 
  5871.                 resources that it is managing, and increases by one the 
  5872.                 use count, which indicates how many pieces of code are 
  5873.                 using a resource.
  5874.  
  5875.  
  5876. æKY CRMGet1IndResource
  5877. æFa CommResources.a
  5878. æFc CommResources.h
  5879. æFp CommResources.p
  5880. æMM
  5881. æTN $A08B A0^.w=$50A (or #1290)
  5882. æDT CRMGet1IndResource(theType: ResType; index: INTEGER): Handle;
  5883. æC -----
  5884. Loading indexed resources
  5885.  
  5886. Function        CRMGet1IndResource(theType: ResType; index: INTEGER): Handle;
  5887.  
  5888.                 CRMGetIndResource and CRMGet1IndResource call the 
  5889.                 Resource Manager routines GetIndResource and 
  5890.                 Get1IndResource, respectively, and return a handle to the
  5891.                 specified communications resource. The Communications 
  5892.                 Resource Manager then adds the handle to the list of 
  5893.                 resources that it is managing, and increases by one the 
  5894.                 use count, which indicates how many pieces of code are 
  5895.                 using a resource.
  5896.  
  5897.  
  5898. æKY CRMGetNamedResource
  5899. æFa CommResources.a
  5900. æFc CommResources.h
  5901. æFp CommResources.p
  5902. æMM
  5903. æTN $A08B A0^.w=$50B (or #1291)
  5904. æDT CRMGetNamedResource(theType: ResType; name: Str255): Handle;
  5905. æC -----
  5906. Loading named resources
  5907.  
  5908. Function        CRMGetNamedResource(theType: ResType; name: Str255): Handle;
  5909.  
  5910.                 CRMGetNamedResource and CRMGet1NamedResource call 
  5911.                 GetNamedResource and Get1NamedResource, respectively, and
  5912.                 return a handle to the specified communications resource.
  5913.                 The Communications Resource Manager then adds the handle 
  5914.                 to the list of resources that it is managing, and 
  5915.                 increases by one the use count, which indicates how many 
  5916.                 pieces of code are using a resource.
  5917.  
  5918.  
  5919. æKY CRMGet1NamedResource
  5920. æFa CommResources.a
  5921. æFc CommResources.h
  5922. æFp CommResources.p
  5923. æMM
  5924. æTN $A08B A0^.w=$50C (or #1292)
  5925. æDT CRMGet1NamedResource(theType: ResType; name: Str255): Handle;
  5926. æC -----
  5927. Loading named resources
  5928.  
  5929. Function        CRMGet1NamedResource(theType: ResType; name: Str255): Handle;
  5930.  
  5931.                 CRMGetNamedResource and CRMGet1NamedResource call 
  5932.                 GetNamedResource and Get1NamedResource, respectively, and
  5933.                 return a handle to the specified communications resource.
  5934.                 The Communications Resource Manager then adds the handle 
  5935.                 to the list of resources that it is managing, and 
  5936.                 increases by one the use count, which indicates how many 
  5937.                 pieces of code are using a resource.
  5938.  
  5939.  
  5940. æKY CRMGetIndex
  5941. æFa CommResources.a
  5942. æFc CommResources.h
  5943. æFp CommResources.p
  5944. æMM
  5945. æTN $A08B A0^.w=$50E (or #1294)
  5946. æDT CRMGetIndex(theHandle: Handle): LONGINT;
  5947. æC -----
  5948. Getting a usage index for a resource
  5949.  
  5950. Function        CRMGetIndex(theHandle: Handle): LONGINT;
  5951.  
  5952.                 CRMGetIndex returns a use count which indicates how many 
  5953.                 pieces of code are simultaneously using a resource with 
  5954.                 the specified handle. CRMGetIndex returns 0 if it does 
  5955.                 not find theHandle in the list of resources the    
  5956.                 Communications Resource Manager is managing.
  5957.  
  5958.  
  5959.  
  5960. æKY CRMReleaseResource
  5961. æFa CommResources.a
  5962. æFc CommResources.h
  5963. æFp CommResources.p
  5964. æMM
  5965. æTN $A08B A0^.w=$50D (or #1293)
  5966. æDT CRMReleaseResource(theHandle: Handle);
  5967. æC -----
  5968. Releasing resources
  5969.  
  5970. Procedure        CRMReleaseResource(theHandle: Handle);
  5971.  
  5972.                 CRMReleaseResource decreases by 1 the value that 
  5973.                 indicates how many pieces of code have requested a 
  5974.                 resource. If the use count reaches 0, the resource 
  5975.                 specified by theHandle is released with a call to the 
  5976.                 Resource Manager routine ReleaseResource.    
  5977.  
  5978.                 Warning:    Your code must release communications 
  5979.                 resources by calling CRMReleaseResource. If your code 
  5980.                 tries to release the resources using the Resource Manager
  5981.                 routine ReleaseResource, the results are unpredictable.          
  5982.  
  5983.  
  5984. æKY CRMLocalToRealID
  5985. æFa CommResources.a
  5986. æFc CommResources.h
  5987. æFp CommResources.p
  5988. æMM
  5989. æTN $A08B A0^.w=$50F (or #1295)
  5990. æDT CRMLocalToRealID(bundleType: ResType; toolID: INTEGER; theKind: ResType; localID: INTEGER): INTEGER;
  5991. æC -----
  5992. Mapping to Real ID
  5993.  
  5994. Function        CRMLocalToRealID(bundleType: ResType; toolID: INTEGER; 
  5995.                     theKind: ResType; localID: INTEGER): INTEGER;
  5996.  
  5997. Description:    CRMLocalToRealID maps a local resource ID to a physical 
  5998.                 resource.    
  5999.  
  6000.                 This routine returns the (physical/local) resource ID if
  6001.                 an appropriate entry exists in the tool bundle resource.
  6002.                 If no entry is found, –1 is returned.
  6003.  
  6004.                 bundleType specifies the type of tool for which the 
  6005.                 mapping is to take place: ClassCM (for connection tools),
  6006.                 ClassTM (for terminal tools), or ClassFT (for file
  6007.                 transfer tools).
  6008.  
  6009.                 toolID specifies the bundle resource for the tool.    
  6010.  
  6011.  
  6012. æKY CRMRealToLocalID
  6013. æFa CommResources.a
  6014. æFc CommResources.h
  6015. æFp CommResources.p
  6016. æMM
  6017. æTN $A08B A0^.w=$510 (or #1296)
  6018. æDT CRMRealToLocalID(bundleType: ResType; toolID: INTEGER; theKind: ResType; realID: INTEGER): INTEGER;
  6019. æC -----
  6020. Mapping to Local ID
  6021.  
  6022. Function        CRMRealToLocalID(bundleType: ResType; toolID: INTEGER; 
  6023.                     theKind: ResType; realID: INTEGER): INTEGER;
  6024.  
  6025. Description:    CRMRealToLocalID maps a physical resource ID to a local 
  6026.                 resource ID.    
  6027.  
  6028.                 This routine returns the (physical/local) resource ID if
  6029.                 an appropriate entry exists in the tool bundle resource. 
  6030.                 If no entry is found, –1 is returned.
  6031.  
  6032.                 bundleType specifies the type of tool for which the
  6033.                 mapping is to take place: ClassCM  (for connection tools),
  6034.                 ClassTM (for terminal tools), or ClassFT (for file 
  6035.                 transfer tools).
  6036.  
  6037.                 Here is the format for a connection tool bundle resource
  6038.                 (in Rez format). The same resource type declaration holds
  6039.                 for terminal tools and file transfer tools.
  6040.  
  6041.                 type 'cbnd' {                    /* or tbnd, or fbnd */
  6042.                     integer = $$CountOf(TypeArray) - 1;
  6043.                     array TypeArray {
  6044.                         literal longint;        /* Type */
  6045.                         integer = $$CountOf(IDArray) - 1;
  6046.                         wide array IDArray {
  6047.                                 integer;        /* Local ID */
  6048.                                 integer;        /* Actual ID */
  6049.                         };    
  6050.                     };
  6051.                 };
  6052.  
  6053.  
  6054. æKY CRMGetIndToolName
  6055. æFa CommResources.a
  6056. æFc CommResources.h
  6057. æFp CommResources.p
  6058. æMM
  6059. æTN $A08B A0^.w=$511 (or #1297)
  6060. æDT CRMGetIndToolName(bundleType: OSType; index: INTEGER; VAR toolName: Str255): OSErr;
  6061. æC -----
  6062. Getting the name of a tool
  6063.  
  6064. Function        CRMGetIndToolName(bundleType: OSType; index: INTEGER;
  6065.                     VAR toolName: Str255): OSErr;
  6066.  
  6067. Description:    CRMGetIndToolName returns the name of a tool in toolName.
  6068.  
  6069.                 The appropriate values for bundleType are as follows:     
  6070.  
  6071.                 CONST
  6072.                     ClassCM         =        'cbnd';
  6073.                     ClassFT         =        'fbnd';
  6074.                     ClassTM            =        'tbnd';
  6075.  
  6076.                 index specifies  which occurrence of a particular type of
  6077.                 tool to return. For example, if index is 2, the 
  6078.                 Communications Resource Manager returns the    name of the 
  6079.                 second tool of a particular type in toolName. If the 
  6080.                 Communications Resource Manager cannot find a tool that 
  6081.                 matches the specified parameters, an empty string is 
  6082.                 returned in toolName.    
  6083.